@aigne/core 1.46.1 → 1.47.0

package/CHANGELOG.md

@@ -12,6 +12,13 @@
   * dependencies
     * @aigne/observability bumped to 0.1.0
 
+## [1.47.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.46.1...core-v1.47.0) (2025-08-11)
+
+
+### Features
+
+* enhance AI agent streaming with thinking mode support ([#343](https://github.com/AIGNE-io/aigne-framework/issues/343)) ([bea2a39](https://github.com/AIGNE-io/aigne-framework/commit/bea2a39a2610c2fe58e46ad612b5103726159ab9))
+
 ## [1.46.1](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.46.0...core-v1.46.1) (2025-08-08)
 
 

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

@@ -258,6 +258,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly description?: string;
     taskTitle?: string;
+    renderTaskTitle(input: I): string | undefined;
     private readonly _inputSchema?;
     defaultInput?: Partial<{
         [key in keyof I]: {
@@ -724,6 +725,7 @@ export interface AgentResponseProgress {
     progress: ({
         event: "agentStarted";
         input: Message;
+        taskTitle?: string;
     } | {
         event: "agentSucceed";
         output: Message;

package/lib/cjs/agents/agent.js

@@ -35,6 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FunctionAgent = exports.Agent = exports.agentOptionsSchema = exports.DEFAULT_INPUT_ACTION_GET = void 0;
 exports.isEmptyChunk = isEmptyChunk;
@@ -44,6 +47,7 @@ exports.textDelta = textDelta;
 exports.jsonDelta = jsonDelta;
 exports.agentProcessResultToObject = agentProcessResultToObject;
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
+const nunjucks_1 = __importDefault(require("nunjucks"));
 const zod_1 = require("zod");
 const logger_js_1 = require("../utils/logger.js");
 const stream_utils_js_1 = require("../utils/stream-utils.js");
@@ -195,6 +199,11 @@ class Agent {
      */
     description;
     taskTitle;
+    renderTaskTitle(input) {
+        if (!this.taskTitle)
+            return;
+        return nunjucks_1.default.renderString(this.taskTitle, { ...input });
+    }
     _inputSchema;
     defaultInput;
     _outputSchema;

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

@@ -64,6 +64,7 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * @default false
      */
     structuredStreamMode?: boolean;
+    ignoreTextOfStructuredStreamMode?: (output: O) => boolean;
     /**
      * Custom structured stream instructions configuration
      *
@@ -273,6 +274,7 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      * @default false
      */
     structuredStreamMode?: boolean;
+    ignoreTextOfStructuredStreamMode?: (output: O) => boolean;
     /**
      * Custom structured stream instructions configuration
      *

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

@@ -118,6 +118,7 @@ class AIAgent extends agent_js_1.Agent {
         if (typeof options.catchToolsError === "boolean")
             this.catchToolsError = options.catchToolsError;
         this.structuredStreamMode = options.structuredStreamMode;
+        this.ignoreTextOfStructuredStreamMode = options.ignoreTextOfStructuredStreamMode;
         this.customStructuredStreamInstructions = options.customStructuredStreamInstructions && {
             ...options.customStructuredStreamInstructions,
             instructions: typeof options.customStructuredStreamInstructions.instructions === "string"
@@ -207,6 +208,7 @@ class AIAgent extends agent_js_1.Agent {
      * @default false
      */
     structuredStreamMode;
+    ignoreTextOfStructuredStreamMode;
     /**
      * Custom structured stream instructions configuration
      *
@@ -248,13 +250,20 @@ class AIAgent extends agent_js_1.Agent {
                 const { metadataStart, metadataEnd, parse } = this.customStructuredStreamInstructions || structured_stream_instructions_js_1.STRUCTURED_STREAM_INSTRUCTIONS;
                 stream = stream.pipeThrough(new structured_stream_extractor_js_1.ExtractMetadataTransform({ start: metadataStart, end: metadataEnd, parse }));
             }
+            let isTextIgnored = false;
             for await (const value of stream) {
                 if ((0, agent_js_1.isAgentResponseDelta)(value)) {
-                    if (value.delta.text?.text) {
+                    if (!isTextIgnored && value.delta.text?.text) {
                         yield { delta: { text: { [outputKey]: value.delta.text.text } } };
                     }
                     if (value.delta.json) {
                         Object.assign(modelOutput, value.delta.json);
+                        if (this.structuredStreamMode) {
+                            yield { delta: { json: value.delta.json.json } };
+                            if (!isTextIgnored && modelOutput.json && this.ignoreTextOfStructuredStreamMode) {
+                                isTextIgnored = this.ignoreTextOfStructuredStreamMode(modelOutput.json);
+                            }
+                        }
                     }
                 }
             }

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

@@ -24,6 +24,7 @@ export interface AgentEvent {
 export interface ContextEventMap {
     agentStarted: [AgentEvent & {
         input: Message;
+        taskTitle?: string;
     }];
     agentSucceed: [AgentEvent & {
         output: Message;

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

@@ -5,8 +5,8 @@ const yaml_1 = require("yaml");
 exports.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>.
+- First, 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>.
+- At the end of the response output the regular response content.
 </output-rules>
 
 <metadata-schema>
@@ -14,11 +14,11 @@ exports.STRUCTURED_STREAM_INSTRUCTIONS = {
 </metadata-schema>
 
 <output-example>
-Here is the regular response content
 <metadata>
 foo: bar
 baz: 123
 </metadata>
+Here is the regular response content
 </output-example>
 `,
     metadataStart: "<metadata>",

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

@@ -132,7 +132,8 @@ class AgentResponseProgressStream extends ReadableStream {
                     controller.close();
                 };
                 const onAgentStarted = (event) => {
-                    writeEvent("agentStarted", event);
+                    const taskTitle = event.agent.renderTaskTitle(event.input);
+                    writeEvent("agentStarted", { ...event, taskTitle });
                 };
                 const onAgentSucceed = (event) => {
                     writeEvent("agentSucceed", event);

package/lib/cjs/utils/stream-utils.d.ts

@@ -23,4 +23,4 @@ export declare function stringToAgentResponseStream(str: string, key?: "text" |
 export declare function toReadableStream(stream: NodeJS.ReadStream): ReadableStream<Uint8Array<ArrayBufferLike>>;
 export declare function readAllString(stream: NodeJS.ReadStream | ReadableStream): Promise<string>;
 export declare function mergeReadableStreams<T1, T2>(s1: ReadableStream<T1>, s2: ReadableStream<T2>): ReadableStream<T1 | T2>;
-export declare function mergeReadableStreams(...streams: ReadableStream<any>[]): ReadableStream<any>;
+export declare function mergeReadableStreams(...streams: (ReadableStream<any> | undefined)[]): ReadableStream<any>;

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

@@ -207,7 +207,7 @@ function mergeReadableStreams(...streams) {
     return new ReadableStream({
         async pull(controller) {
             try {
-                readers ??= streams.map((s) => ({ reader: s.getReader(), data: [] }));
+                readers ??= streams.filter(type_utils_js_1.isNonNullable).map((s) => ({ reader: s.getReader(), data: [] }));
                 while (readers.length) {
                     const chunk = await Promise.race(readers.map((i) => {
                         i.reading ??= i.reader.read().then((result) => ({ result, item: i }));

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

@@ -258,6 +258,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly description?: string;
     taskTitle?: string;
+    renderTaskTitle(input: I): string | undefined;
     private readonly _inputSchema?;
     defaultInput?: Partial<{
         [key in keyof I]: {
@@ -724,6 +725,7 @@ export interface AgentResponseProgress {
     progress: ({
         event: "agentStarted";
         input: Message;
+        taskTitle?: string;
     } | {
         event: "agentSucceed";
         output: Message;

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

@@ -64,6 +64,7 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * @default false
      */
     structuredStreamMode?: boolean;
+    ignoreTextOfStructuredStreamMode?: (output: O) => boolean;
     /**
      * Custom structured stream instructions configuration
      *
@@ -273,6 +274,7 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      * @default false
      */
     structuredStreamMode?: boolean;
+    ignoreTextOfStructuredStreamMode?: (output: O) => boolean;
     /**
      * Custom structured stream instructions configuration
      *

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

@@ -24,6 +24,7 @@ export interface AgentEvent {
 export interface ContextEventMap {
     agentStarted: [AgentEvent & {
         input: Message;
+        taskTitle?: string;
     }];
     agentSucceed: [AgentEvent & {
         output: Message;

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

@@ -23,4 +23,4 @@ export declare function stringToAgentResponseStream(str: string, key?: "text" |
 export declare function toReadableStream(stream: NodeJS.ReadStream): ReadableStream<Uint8Array<ArrayBufferLike>>;
 export declare function readAllString(stream: NodeJS.ReadStream | ReadableStream): Promise<string>;
 export declare function mergeReadableStreams<T1, T2>(s1: ReadableStream<T1>, s2: ReadableStream<T2>): ReadableStream<T1 | T2>;
-export declare function mergeReadableStreams(...streams: ReadableStream<any>[]): ReadableStream<any>;
+export declare function mergeReadableStreams(...streams: (ReadableStream<any> | undefined)[]): ReadableStream<any>;

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

@@ -258,6 +258,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly description?: string;
     taskTitle?: string;
+    renderTaskTitle(input: I): string | undefined;
     private readonly _inputSchema?;
     defaultInput?: Partial<{
         [key in keyof I]: {
@@ -724,6 +725,7 @@ export interface AgentResponseProgress {
     progress: ({
         event: "agentStarted";
         input: Message;
+        taskTitle?: string;
     } | {
         event: "agentSucceed";
         output: Message;

package/lib/esm/agents/agent.js

@@ -1,4 +1,5 @@
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
+import nunjucks from "nunjucks";
 import { ZodObject, z } from "zod";
 import { logger } from "../utils/logger.js";
 import { agentResponseStreamToObject, asyncGeneratorToReadableStream, isAsyncGenerator, objectToAgentResponseStream, onAgentResponseStreamEnd, } from "../utils/stream-utils.js";
@@ -150,6 +151,11 @@ export class Agent {
      */
     description;
     taskTitle;
+    renderTaskTitle(input) {
+        if (!this.taskTitle)
+            return;
+        return nunjucks.renderString(this.taskTitle, { ...input });
+    }
     _inputSchema;
     defaultInput;
     _outputSchema;

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

@@ -64,6 +64,7 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * @default false
      */
     structuredStreamMode?: boolean;
+    ignoreTextOfStructuredStreamMode?: (output: O) => boolean;
     /**
      * Custom structured stream instructions configuration
      *
@@ -273,6 +274,7 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      * @default false
      */
     structuredStreamMode?: boolean;
+    ignoreTextOfStructuredStreamMode?: (output: O) => boolean;
     /**
      * Custom structured stream instructions configuration
      *

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

@@ -115,6 +115,7 @@ export class AIAgent extends Agent {
         if (typeof options.catchToolsError === "boolean")
             this.catchToolsError = options.catchToolsError;
         this.structuredStreamMode = options.structuredStreamMode;
+        this.ignoreTextOfStructuredStreamMode = options.ignoreTextOfStructuredStreamMode;
         this.customStructuredStreamInstructions = options.customStructuredStreamInstructions && {
             ...options.customStructuredStreamInstructions,
             instructions: typeof options.customStructuredStreamInstructions.instructions === "string"
@@ -204,6 +205,7 @@ export class AIAgent extends Agent {
      * @default false
      */
     structuredStreamMode;
+    ignoreTextOfStructuredStreamMode;
     /**
      * Custom structured stream instructions configuration
      *
@@ -245,13 +247,20 @@ export class AIAgent extends Agent {
                 const { metadataStart, metadataEnd, parse } = this.customStructuredStreamInstructions || STRUCTURED_STREAM_INSTRUCTIONS;
                 stream = stream.pipeThrough(new ExtractMetadataTransform({ start: metadataStart, end: metadataEnd, parse }));
             }
+            let isTextIgnored = false;
             for await (const value of stream) {
                 if (isAgentResponseDelta(value)) {
-                    if (value.delta.text?.text) {
+                    if (!isTextIgnored && value.delta.text?.text) {
                         yield { delta: { text: { [outputKey]: value.delta.text.text } } };
                     }
                     if (value.delta.json) {
                         Object.assign(modelOutput, value.delta.json);
+                        if (this.structuredStreamMode) {
+                            yield { delta: { json: value.delta.json.json } };
+                            if (!isTextIgnored && modelOutput.json && this.ignoreTextOfStructuredStreamMode) {
+                                isTextIgnored = this.ignoreTextOfStructuredStreamMode(modelOutput.json);
+                            }
+                        }
                     }
                 }
             }

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

@@ -24,6 +24,7 @@ export interface AgentEvent {
 export interface ContextEventMap {
     agentStarted: [AgentEvent & {
         input: Message;
+        taskTitle?: string;
     }];
     agentSucceed: [AgentEvent & {
         output: Message;

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

@@ -2,8 +2,8 @@ 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>.
+- First, 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>.
+- At the end of the response output the regular response content.
 </output-rules>
 
 <metadata-schema>
@@ -11,11 +11,11 @@ export const STRUCTURED_STREAM_INSTRUCTIONS = {
 </metadata-schema>
 
 <output-example>
-Here is the regular response content
 <metadata>
 foo: bar
 baz: 123
 </metadata>
+Here is the regular response content
 </output-example>
 `,
     metadataStart: "<metadata>",

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

@@ -126,7 +126,8 @@ export class AgentResponseProgressStream extends ReadableStream {
                     controller.close();
                 };
                 const onAgentStarted = (event) => {
-                    writeEvent("agentStarted", event);
+                    const taskTitle = event.agent.renderTaskTitle(event.input);
+                    writeEvent("agentStarted", { ...event, taskTitle });
                 };
                 const onAgentSucceed = (event) => {
                     writeEvent("agentSucceed", event);

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

@@ -23,4 +23,4 @@ export declare function stringToAgentResponseStream(str: string, key?: "text" |
 export declare function toReadableStream(stream: NodeJS.ReadStream): ReadableStream<Uint8Array<ArrayBufferLike>>;
 export declare function readAllString(stream: NodeJS.ReadStream | ReadableStream): Promise<string>;
 export declare function mergeReadableStreams<T1, T2>(s1: ReadableStream<T1>, s2: ReadableStream<T2>): ReadableStream<T1 | T2>;
-export declare function mergeReadableStreams(...streams: ReadableStream<any>[]): ReadableStream<any>;
+export declare function mergeReadableStreams(...streams: (ReadableStream<any> | undefined)[]): ReadableStream<any>;

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

@@ -1,6 +1,6 @@
 import equal from "fast-deep-equal";
 import { isAgentResponseDelta, isEmptyChunk, } from "../agents/agent.js";
-import { isRecord, omitBy } from "./type-utils.js";
+import { isNonNullable, isRecord, omitBy } from "./type-utils.js";
 import "./stream-polyfill.js";
 export function objectToAgentResponseStream(json) {
     if (!isRecord(json)) {
@@ -189,7 +189,7 @@ export function mergeReadableStreams(...streams) {
     return new ReadableStream({
         async pull(controller) {
             try {
-                readers ??= streams.map((s) => ({ reader: s.getReader(), data: [] }));
+                readers ??= streams.filter(isNonNullable).map((s) => ({ reader: s.getReader(), data: [] }));
                 while (readers.length) {
                     const chunk = await Promise.race(readers.map((i) => {
                         i.reading ??= i.reader.read().then((result) => ({ result, item: i }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.46.1",
+  "version": "1.47.0",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"