@aigne/core 1.18.6 → 1.20.1

package/CHANGELOG.md

@@ -5,6 +5,34 @@
 
 * add user context support ([#131](https://github.com/AIGNE-io/aigne-framework/issues/131)) ([4dd9d20](https://github.com/AIGNE-io/aigne-framework/commit/4dd9d20953f6ac33933723db56efd9b44bafeb02))
 
+## [1.20.1](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.20.0...core-v1.20.1) (2025-06-19)
+
+
+### Bug Fixes
+
+* use `inputKey` instead of implicit $message for AIAgent ([#165](https://github.com/AIGNE-io/aigne-framework/issues/165)) ([8b6e589](https://github.com/AIGNE-io/aigne-framework/commit/8b6e5896bba8209fd2eecb0f5b9263618bffdaf8))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/platform-helpers bumped to 0.1.2
+
+## [1.20.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.19.0...core-v1.20.0) (2025-06-17)
+
+
+### Features
+
+* support return $meta output by enable returnMetadata option ([#163](https://github.com/AIGNE-io/aigne-framework/issues/163)) ([ac73759](https://github.com/AIGNE-io/aigne-framework/commit/ac73759615d44a09fa71b3bfbd3e9356ffe1d2ed))
+
+## [1.19.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.18.6...core-v1.19.0) (2025-06-16)
+
+
+### Features
+
+* support respond progressing chunks by enable `returnProgressChunks` option for aigne.invoke ([cf4c313](https://github.com/AIGNE-io/aigne-framework/commit/cf4c313ee69f255be799ac196da675b79f69bf76))
+
 ## [1.18.6](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.18.5...core-v1.18.6) (2025-06-11)
 
 

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

@@ -1,7 +1,8 @@
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { ZodObject, type ZodType } from "zod";
-import type { Context, UserContext } from "../aigne/context.js";
+import type { AgentEvent, Context, UserContext } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
+import type { ContextUsage } from "../aigne/usage.js";
 import type { Memory, MemoryAgent } from "../memory/memory.js";
 import type { MemoryRecorderInput } from "../memory/recorder.js";
 import type { MemoryRetrieverInput } from "../memory/retriever.js";
@@ -12,7 +13,11 @@ export * from "./types.js";
 /**
  * Basic message type that can contain any key-value pairs
  */
-export type Message = Record<string, unknown>;
+export interface Message extends Record<string, unknown> {
+    $meta?: {
+        usage: ContextUsage;
+    };
+}
 /**
  * Topics the agent subscribes to, can be a single topic string or an array of topic strings
  */
@@ -328,7 +333,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Regular mode waits for the agent to complete processing and return the final result,
      * suitable for scenarios where a complete result is needed at once.
      *
-     * @param input Input message to the agent, can be a string or structured object
+     * @param input Input message to the agent
      * @param options Invocation options, must set streaming to false or leave unset
      * @returns Final JSON response
      *
@@ -336,7 +341,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Here's an example of invoking an agent with regular mode:
      * {@includeCode ../../test/agents/agent.test.ts#example-invoke}
      */
-    invoke(input: I | string, options?: Partial<AgentInvokeOptions> & {
+    invoke(input: I, options?: Partial<AgentInvokeOptions> & {
         streaming?: false;
     }): Promise<O>;
     /**
@@ -346,7 +351,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * suitable for scenarios requiring real-time progress updates, such as
      * chat bot typing effects.
      *
-     * @param input Input message to the agent, can be a string or structured object
+     * @param input Input message to the agent
      * @param options Invocation options, must set streaming to true for this overload
      * @returns Streaming response object
      *
@@ -354,7 +359,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Here's an example of invoking an agent with streaming response:
      * {@includeCode ../../test/agents/agent.test.ts#example-invoke-streaming}
      */
-    invoke(input: I | string, options: Partial<AgentInvokeOptions> & {
+    invoke(input: I, options: Partial<AgentInvokeOptions> & {
         streaming: true;
     }): Promise<AgentResponseStream<O>>;
     /**
@@ -366,7 +371,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * @param options Invocation options
      * @returns Agent response (streaming or regular)
      */
-    invoke(input: I | string, options?: Partial<AgentInvokeOptions>): Promise<AgentResponse<O>>;
+    invoke(input: I, options?: Partial<AgentInvokeOptions>): Promise<AgentResponse<O>>;
     protected invokeSkill<I extends Message, O extends Message>(skill: Agent<I, O>, input: I, options: AgentInvokeOptions): Promise<O>;
     /**
      * Process agent output
@@ -594,7 +599,7 @@ export type AgentResponseStream<T> = ReadableStream<AgentResponseChunk<T>>;
  *
  * @template T Response data type
  */
-export type AgentResponseChunk<T> = AgentResponseDelta<T>;
+export type AgentResponseChunk<T> = AgentResponseDelta<T> | AgentResponseProgress;
 /**
  * Check if a response chunk is empty
  *
@@ -622,6 +627,24 @@ export interface AgentResponseDelta<T> {
         json?: Partial<T> | TransferAgentOutput;
     };
 }
+export declare function isAgentResponseDelta<T>(chunk: AgentResponseChunk<T>): chunk is AgentResponseDelta<T>;
+export interface AgentResponseProgress {
+    progress: ({
+        event: "agentStarted";
+        input: Message;
+    } | {
+        event: "agentSucceed";
+        output: Message;
+    } | {
+        event: "agentFailed";
+        error: Error;
+    }) & Omit<AgentEvent, "agent"> & {
+        agent: {
+            name: string;
+        };
+    };
+}
+export declare function isAgentResponseProgress<T>(chunk: AgentResponseChunk<T>): chunk is AgentResponseProgress;
 /**
  * Creates a text delta for streaming responses
  *

package/lib/cjs/agents/agent.js

@@ -38,11 +38,12 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FunctionAgent = exports.Agent = exports.agentOptionsSchema = void 0;
 exports.isEmptyChunk = isEmptyChunk;
+exports.isAgentResponseDelta = isAgentResponseDelta;
+exports.isAgentResponseProgress = isAgentResponseProgress;
 exports.textDelta = textDelta;
 exports.jsonDelta = jsonDelta;
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const zod_1 = require("zod");
-const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const logger_js_1 = require("../utils/logger.js");
 const stream_utils_js_1 = require("../utils/stream-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
@@ -315,7 +316,7 @@ class Agent {
         for (const memory of this.memories) {
             const ms = (await memory.retrieve({
                 ...input,
-                search: typeof input === "string" ? input : input && (0, prompt_builder_js_1.getMessage)(input),
+                search: typeof input.search === "string" ? input.search : JSON.stringify(input.search),
                 limit: input.limit ?? this.maxRetrieveMemoryCount,
             }, options.context)).memories;
             memories.push(...ms);
@@ -342,13 +343,12 @@ class Agent {
             opts.context.memories.push(...options.memories);
             options.memories = undefined;
         }
-        const message = typeof input === "string" ? (0, prompt_builder_js_1.createMessage)(input) : input;
         logger_js_1.logger.debug("Invoke agent %s started with input: %O", this.name, input);
         if (!this.disableEvents)
-            opts.context.emit("agentStarted", { agent: this, input: message });
+            opts.context.emit("agentStarted", { agent: this, input });
         try {
-            await this.hooks.onStart?.({ context: opts.context, input: message });
-            const parsedInput = (0, type_utils_js_1.checkArguments)(`Agent ${this.name} input`, this.inputSchema, message);
+            await this.hooks.onStart?.({ context: opts.context, input });
+            const parsedInput = (0, type_utils_js_1.checkArguments)(`Agent ${this.name} input`, this.inputSchema, input);
             await this.preprocess(parsedInput, opts);
             this.checkContextStatus(opts);
             let response = await this.process(parsedInput, opts);
@@ -361,22 +361,23 @@ class Agent {
                     : (0, stream_utils_js_1.isAsyncGenerator)(response)
                         ? (0, stream_utils_js_1.asyncGeneratorToReadableStream)(response)
                         : (0, stream_utils_js_1.objectToAgentResponseStream)(response);
-                return this.checkResponseByGuideRails(message, (0, stream_utils_js_1.onAgentResponseStreamEnd)(stream, async (result) => {
-                    return await this.processAgentOutput(parsedInput, result, opts);
-                }, {
-                    errorCallback: async (error) => {
-                        return await this.processAgentError(message, error, opts);
+                return this.checkResponseByGuideRails(input, (0, stream_utils_js_1.onAgentResponseStreamEnd)(stream, {
+                    onResult: async (result) => {
+                        return await this.processAgentOutput(parsedInput, result, opts);
+                    },
+                    onError: async (error) => {
+                        return await this.processAgentError(input, error, opts);
                     },
                 }), opts);
             }
-            return await this.checkResponseByGuideRails(message, this.processAgentOutput(parsedInput, response instanceof ReadableStream
+            return await this.checkResponseByGuideRails(input, this.processAgentOutput(parsedInput, response instanceof ReadableStream
                 ? await (0, stream_utils_js_1.agentResponseStreamToObject)(response)
                 : (0, stream_utils_js_1.isAsyncGenerator)(response)
                     ? await (0, stream_utils_js_1.agentResponseStreamToObject)(response)
                     : response, opts), opts);
         }
         catch (error) {
-            throw await this.processAgentError(message, error, opts);
+            throw await this.processAgentError(input, error, opts);
         }
     }
     async invokeSkill(skill, input, options) {
@@ -464,14 +465,16 @@ class Agent {
             return output;
         const result = await output;
         if (result instanceof ReadableStream) {
-            return (0, stream_utils_js_1.onAgentResponseStreamEnd)(result, async (result) => {
-                const error = await this.runGuideRails(input, result, options);
-                if (error) {
-                    return {
-                        ...(await this.onGuideRailError(error)),
-                        $status: "GuideRailError",
-                    };
-                }
+            return (0, stream_utils_js_1.onAgentResponseStreamEnd)(result, {
+                onResult: async (result) => {
+                    const error = await this.runGuideRails(input, result, options);
+                    if (error) {
+                        return {
+                            ...(await this.onGuideRailError(error)),
+                            $status: "GuideRailError",
+                        };
+                    }
+                },
             });
         }
         const error = await this.runGuideRails(input, result, options);
@@ -585,7 +588,13 @@ exports.Agent = Agent;
  * @returns True if the chunk is empty
  */
 function isEmptyChunk(chunk) {
-    return (0, type_utils_js_1.isEmpty)(chunk.delta.json) && (0, type_utils_js_1.isEmpty)(chunk.delta.text);
+    return isAgentResponseDelta(chunk) && (0, type_utils_js_1.isEmpty)(chunk.delta.json) && (0, type_utils_js_1.isEmpty)(chunk.delta.text);
+}
+function isAgentResponseDelta(chunk) {
+    return "delta" in chunk;
+}
+function isAgentResponseProgress(chunk) {
+    return "progress" in chunk;
 }
 /**
  * Creates a text delta for streaming responses

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

@@ -12,7 +12,7 @@ import type { GuideRailAgentOutput } from "./guide-rail-agent.js";
  * @template I The input message type the agent accepts
  * @template O The output message type the agent returns
  */
-export interface AIAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
+export interface AIAgentOptions<InputKey extends string = string, I extends Message & InputMessage<InputKey> = Message & InputMessage<InputKey>, O extends Message = Message> extends AgentOptions<Omit<I, InputKey> & Partial<InputMessage<InputKey>>, O> {
     /**
      * The language model to use for this agent
      *
@@ -26,10 +26,14 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * more complex prompt templates
      */
     instructions?: string | PromptBuilder;
+    /**
+     * Pick a message from input to use as the user's message
+     */
+    inputKey?: InputKey;
     /**
      * Custom key to use for text output in the response
      *
-     * Defaults to $message if not specified
+     * Defaults to `message` if not specified
      */
     outputKey?: string;
     /**
@@ -106,6 +110,9 @@ export declare const aiAgentToolChoiceSchema: z.ZodUnion<[z.ZodNativeEnum<typeof
 export declare const aiAgentOptionsSchema: ZodObject<{
     [key in keyof AIAgentOptions]: ZodType<AIAgentOptions[key]>;
 }>;
+type InputMessage<K> = K extends string ? {
+    [key in K]: string;
+} : Message;
 /**
  * AI-powered agent that leverages language models
  *
@@ -126,7 +133,7 @@ export declare const aiAgentOptionsSchema: ZodObject<{
  * Basic AIAgent creation:
  * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-basic}
  */
-export declare class AIAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+export declare class AIAgent<InputKey extends string = string, I extends Message & InputMessage<InputKey> = Message & InputMessage<InputKey>, O extends Message = Message> extends Agent<I, O> {
     /**
      * Create an AIAgent with the specified options
      *
@@ -139,13 +146,13 @@ export declare class AIAgent<I extends Message = Message, O extends Message = Me
      * AI agent with custom instructions:
      * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-instructions}
      */
-    static from<I extends Message, O extends Message>(options: AIAgentOptions<I, O>): AIAgent<I, O>;
+    static from<InputKey extends string, I extends Message & InputMessage<InputKey>, O extends Message>(options: AIAgentOptions<InputKey, I, O>): AIAgent<InputKey, I, O>;
     /**
      * Create an AIAgent instance
      *
      * @param options Configuration options for the AI agent
      */
-    constructor(options: AIAgentOptions<I, O>);
+    constructor(options: AIAgentOptions<InputKey, I, O>);
     /**
      * The language model used by this agent
      *
@@ -163,6 +170,10 @@ export declare class AIAgent<I extends Message = Message, O extends Message = Me
      * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-prompt-builder}
      */
     instructions: PromptBuilder;
+    /**
+     * Pick a message from input to use as the user's message
+     */
+    inputKey?: InputKey;
     /**
      * Custom key to use for text output in the response
      *
@@ -170,7 +181,7 @@ export declare class AIAgent<I extends Message = Message, O extends Message = Me
      * Setting a custom output key:
      * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-custom-output-key}
      */
-    outputKey?: string;
+    outputKey: string;
     /**
      * Controls how the agent uses tools during execution
      *
@@ -224,3 +235,4 @@ export declare class AIAgent<I extends Message = Message, O extends Message = Me
      */
     _processRouter(input: I, model: ChatModel, modelInput: ChatModelInput, options: AgentInvokeOptions, toolsMap: Map<string, Agent>): AgentProcessAsyncGenerator<O>;
 }
+export {};

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

@@ -8,6 +8,7 @@ const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_1 = require("./agent.js");
 const chat_model_js_1 = require("./chat-model.js");
 const types_js_1 = require("./types.js");
+const DEFAULT_OUTPUT_KEY = "message";
 /**
  * Tool choice options for AI agents
  *
@@ -52,6 +53,7 @@ exports.aiAgentToolChoiceSchema = zod_1.z.union([zod_1.z.nativeEnum(AIAgentToolC
 exports.aiAgentOptionsSchema = agent_js_1.agentOptionsSchema.extend({
     model: zod_1.z.instanceof(chat_model_js_1.ChatModel).optional(),
     instructions: zod_1.z.union([zod_1.z.string(), zod_1.z.instanceof(prompt_builder_js_1.PromptBuilder)]).optional(),
+    inputKey: zod_1.z.string().optional(),
     outputKey: zod_1.z.string().optional(),
     toolChoice: exports.aiAgentToolChoiceSchema.optional(),
     memoryAgentsAsTools: zod_1.z.boolean().optional(),
@@ -99,19 +101,23 @@ class AIAgent extends agent_js_1.Agent {
      * @param options Configuration options for the AI agent
      */
     constructor(options) {
-        super(options);
+        super({ ...options, inputSchema: options.inputSchema });
         (0, type_utils_js_1.checkArguments)("AIAgent", exports.aiAgentOptionsSchema, options);
         this.model = options.model;
         this.instructions =
             typeof options.instructions === "string"
                 ? prompt_builder_js_1.PromptBuilder.from(options.instructions)
                 : (options.instructions ?? new prompt_builder_js_1.PromptBuilder());
-        this.outputKey = options.outputKey;
+        this.inputKey = options.inputKey;
+        this.outputKey = options.outputKey || DEFAULT_OUTPUT_KEY;
         this.toolChoice = options.toolChoice;
         this.memoryAgentsAsTools = options.memoryAgentsAsTools;
         this.memoryPromptTemplate = options.memoryPromptTemplate;
         if (typeof options.catchToolsError === "boolean")
             this.catchToolsError = options.catchToolsError;
+        if (!this.inputKey && !this.instructions) {
+            throw new Error("AIAgent requires either inputKey or instructions to be set");
+        }
     }
     /**
      * The language model used by this agent
@@ -130,6 +136,10 @@ class AIAgent extends agent_js_1.Agent {
      * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-prompt-builder}
      */
     instructions;
+    /**
+     * Pick a message from input to use as the user's message
+     */
+    inputKey;
     /**
      * Custom key to use for text output in the response
      *
@@ -191,20 +201,21 @@ class AIAgent extends agent_js_1.Agent {
         });
         const toolsMap = new Map(toolAgents?.map((i) => [i.name, i]));
         if (this.toolChoice === "router") {
-            yield* this._processRouter(input, model, modelInput, options, toolsMap);
-            return;
+            return yield* this._processRouter(input, model, modelInput, options, toolsMap);
         }
         const toolCallMessages = [];
-        const outputKey = this.outputKey || prompt_builder_js_1.MESSAGE_KEY;
+        const outputKey = this.outputKey;
         for (;;) {
             const modelOutput = {};
             const stream = await options.context.invoke(model, { ...modelInput, messages: modelInput.messages.concat(toolCallMessages) }, { streaming: true });
             for await (const value of stream) {
-                if (value.delta.text?.text) {
-                    yield { delta: { text: { [outputKey]: value.delta.text.text } } };
-                }
-                if (value.delta.json) {
-                    Object.assign(modelOutput, value.delta.json);
+                if ((0, agent_js_1.isAgentResponseDelta)(value)) {
+                    if (value.delta.text?.text) {
+                        yield { delta: { text: { [outputKey]: value.delta.text.text } } };
+                    }
+                    if (value.delta.json) {
+                        Object.assign(modelOutput, value.delta.json);
+                    }
                 }
             }
             const { toolCalls, json, text } = modelOutput;
@@ -253,7 +264,7 @@ class AIAgent extends agent_js_1.Agent {
         }
     }
     async onGuideRailError(error) {
-        const outputKey = this.outputKey || prompt_builder_js_1.MESSAGE_KEY;
+        const outputKey = this.outputKey || DEFAULT_OUTPUT_KEY;
         return {
             [outputKey]: error.reason,
         };
@@ -275,7 +286,7 @@ class AIAgent extends agent_js_1.Agent {
         if (!tool)
             throw new Error(`Tool not found: ${call.function.name}`);
         const stream = await options.context.invoke(tool, { ...call.function.arguments, ...input }, { streaming: true, sourceAgent: this });
-        yield* stream;
+        return yield* stream;
     }
 }
 exports.AIAgent = AIAgent;

package/lib/cjs/agents/guide-rail-agent.d.ts

@@ -59,4 +59,4 @@ export interface GuideRailAgentOutput extends Message {
  * - Monitor and audit agent behavior
  */
 export type GuideRailAgent = Agent<GuideRailAgentInput, GuideRailAgentOutput>;
-export declare const guideRailAgentOptions: AgentOptions<GuideRailAgentInput, GuideRailAgentOutput>;
+export declare const guideRailAgentOptions: AgentOptions<any, GuideRailAgentOutput>;

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

@@ -192,7 +192,7 @@ export declare abstract class MCPBase<I extends Message, O extends Message> exte
 export declare class MCPTool extends MCPBase<Message, CallToolResult> {
     process(input: Message): Promise<CallToolResult>;
 }
-export interface MCPPromptInput extends Message {
+export interface MCPPromptInput extends Record<string, unknown> {
     [key: string]: string;
 }
 export declare class MCPPrompt extends MCPBase<MCPPromptInput, GetPromptResult> {

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

@@ -158,7 +158,7 @@ class TeamAgent extends agent_js_1.Agent {
             if (!done) {
                 tasks.set(index, read(index, reader));
             }
-            if (value) {
+            if (value && (0, agent_js_1.isAgentResponseDelta)(value)) {
                 let { delta: { text, ...delta }, } = value;
                 if (text) {
                     for (const key of Object.keys(text)) {

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

@@ -129,12 +129,12 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * This overload is useful when you need to track which agent was ultimately responsible for generating the response.
      *
      * @param agent - Target agent to invoke
-     * @param message - Input message to send to the agent (can be a string or a structured message object)
+     * @param message - Input message to send to the agent
      * @param options.returnActiveAgent - Must be true to return the final active agent
      * @param options.streaming - Must be false to return a response stream
      * @returns A promise resolving to a tuple containing the agent's response and the final active agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions<U> & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions<U> & {
         returnActiveAgent: true;
         streaming?: false;
     }): Promise<[O, Agent]>;
@@ -143,12 +143,12 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * This overload is useful when you need streaming responses while also tracking which agent provided them.
      *
      * @param agent - Target agent to invoke
-     * @param message - Input message to send to the agent (can be a string or a structured message object)
+     * @param message - Input message to send to the agent
      * @param options.returnActiveAgent - Must be true to return the final active agent
      * @param options.streaming - Must be true to return a response stream
      * @returns A promise resolving to a tuple containing the agent's response stream and a promise for the final agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions<U> & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions<U> & {
         returnActiveAgent: true;
         streaming: true;
     }): Promise<[AgentResponseStream<O>, Promise<Agent>]>;
@@ -157,7 +157,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * This is the standard way to invoke an agent when you only need the response.
      *
      * @param agent - Target agent to invoke
-     * @param message - Input message to send to the agent (can be a string or a structured message object)
+     * @param message - Input message to send to the agent
      * @param options - Optional configuration parameters for the invocation
      * @returns A promise resolving to the agent's complete response
      *
@@ -165,7 +165,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * Here's a simple example of how to invoke an agent:
      * {@includeCode ../../test/aigne/aigne.test.ts#example-simple}
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options?: InvokeOptions<U> & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options?: InvokeOptions<U> & {
         returnActiveAgent?: false;
         streaming?: false;
     }): Promise<O>;
@@ -174,7 +174,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * This allows processing the response incrementally as it's being generated.
      *
      * @param agent - Target agent to invoke
-     * @param message - Input message to send to the agent (can be a string or a structured message object)
+     * @param message - Input message to send to the agent
      * @param options - Configuration with streaming enabled to receive incremental response chunks
      * @returns A promise resolving to a stream of the agent's response that can be consumed incrementally
      *
@@ -182,7 +182,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * Here's an example of how to invoke an agent with streaming response:
      * {@includeCode ../../test/aigne/aigne.test.ts#example-streaming}
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions<U> & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions<U> & {
         returnActiveAgent?: false;
         streaming: true;
     }): Promise<AgentResponseStream<O>>;
@@ -196,7 +196,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * @returns Either a UserAgent (when no message provided) or a promise resolving to the agent's response
      * with optional active agent information based on the provided options
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I | string, options?: InvokeOptions<U>): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I, options?: InvokeOptions<U>): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
     /**
      * Publishes a message to the message queue for inter-agent communication.
      * This method broadcasts a message to all subscribers of the specified topic(s).
@@ -210,7 +210,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * Here's an example of how to publish a message:
      * {@includeCode ../../test/aigne/aigne.test.ts#example-publish-message}
      */
-    publish(topic: string | string[], payload: Omit<MessagePayload, "context"> | Message | string, options?: InvokeOptions<U>): void;
+    publish(topic: string | string[], payload: Omit<MessagePayload, "context"> | Message, options?: InvokeOptions<U>): void;
     /**
      * Subscribes to receive the next message on a specific topic.
      * This overload returns a Promise that resolves with the next message published to the topic.

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

@@ -41,6 +41,8 @@ export type ContextEmitEventMap = {
  */
 export interface InvokeOptions<U extends UserContext = UserContext> extends Partial<Omit<AgentInvokeOptions<U>, "context">> {
     returnActiveAgent?: boolean;
+    returnProgressChunks?: boolean;
+    returnMetadata?: boolean;
     disableTransfer?: boolean;
     sourceAgent?: Agent;
 }
@@ -53,6 +55,8 @@ export interface UserContext extends Record<string, unknown> {
  * @hidden
  */
 export interface Context<U extends UserContext = UserContext> extends TypedEventEmitter<ContextEventMap, ContextEmitEventMap> {
+    id: string;
+    parentId?: string;
     model?: ChatModel;
     skills?: Agent[];
     usage: ContextUsage;
@@ -74,11 +78,11 @@ export interface Context<U extends UserContext = UserContext> extends TypedEvent
      * @param options.streaming return a stream of the output
      * @returns the output of the agent and the final active agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions & {
         returnActiveAgent: true;
         streaming?: false;
     }): Promise<[O, Agent]>;
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions & {
         returnActiveAgent: true;
         streaming: true;
     }): Promise<[AgentResponseStream<O>, Promise<Agent>]>;
@@ -88,19 +92,19 @@ export interface Context<U extends UserContext = UserContext> extends TypedEvent
      * @param message Message to pass to the agent
      * @returns the output of the agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options?: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options?: InvokeOptions & {
         streaming?: false;
     }): Promise<O>;
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I, options: InvokeOptions & {
         streaming: true;
     }): Promise<AgentResponseStream<O>>;
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I | string, options?: InvokeOptions): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I, options?: InvokeOptions): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
     /**
      * Publish a message to a topic, the aigne will invoke the listeners of the topic
      * @param topic topic name, or an array of topic names
      * @param payload message to publish
      */
-    publish(topic: string | string[], payload: Omit<MessagePayload, "context"> | Message | string, options?: InvokeOptions): void;
+    publish(topic: string | string[], payload: Omit<MessagePayload, "context"> | Message, options?: InvokeOptions): void;
     subscribe(topic: string | string[], listener?: undefined): Promise<MessagePayload>;
     subscribe(topic: string | string[], listener: MessageQueueListener): Unsubscribe;
     subscribe(topic: string | string[], listener?: MessageQueueListener): Unsubscribe | Promise<MessagePayload>;
@@ -139,6 +143,7 @@ export declare class AIGNEContext implements Context {
         reset?: boolean;
     }): AIGNEContext;
     invoke: Context["invoke"];
+    private onInvocationResult;
     publish: Context["publish"];
     subscribe: Context["subscribe"];
     unsubscribe: Context["unsubscribe"];