@aigne/core 1.19.0 → 1.21.0

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.21.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.20.1...core-v1.21.0) (2025-06-20)
+
+
+### Features
+
+* **cli:** support pass named input to agent by --input-xxx ([#167](https://github.com/AIGNE-io/aigne-framework/issues/167)) ([cda5bb6](https://github.com/AIGNE-io/aigne-framework/commit/cda5bb6baab680787de1a042664fe34c17a84bb1))
+
+## [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)
 
 

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

@@ -2,6 +2,7 @@ import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { ZodObject, type ZodType } from "zod";
 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 & Message, 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 & Message, options: Partial<AgentInvokeOptions> & {
         streaming: true;
     }): Promise<AgentResponseStream<O>>;
     /**
@@ -366,8 +371,8 @@ 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>>;
-    protected invokeSkill<I extends Message, O extends Message>(skill: Agent<I, O>, input: I, options: AgentInvokeOptions): Promise<O>;
+    invoke(input: I & Message, options?: Partial<AgentInvokeOptions>): Promise<AgentResponse<O>>;
+    protected invokeSkill<I extends Message, O extends Message>(skill: Agent<I, O>, input: I & Message, options: AgentInvokeOptions): Promise<O>;
     /**
      * Process agent output
      *

package/lib/cjs/agents/agent.js

@@ -44,7 +44,6 @@ 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");
@@ -317,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);
@@ -344,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);
@@ -363,23 +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, {
+                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(message, error, opts);
+                        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) {

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

@@ -3,6 +3,7 @@ import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
 import { ChatModel, type ChatModelInput } from "./chat-model.js";
 import type { GuideRailAgentOutput } from "./guide-rail-agent.js";
+export declare const DEFAULT_OUTPUT_KEY = "message";
 /**
  * Configuration options for an AI Agent
  *
@@ -26,10 +27,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?: string;
     /**
      * Custom key to use for text output in the response
      *
-     * Defaults to $message if not specified
+     * Defaults to `message` if not specified
      */
     outputKey?: string;
     /**
@@ -163,6 +168,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?: string;
     /**
      * Custom key to use for text output in the response
      *
@@ -170,7 +179,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
      *

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AIAgent = exports.aiAgentOptionsSchema = exports.aiAgentToolChoiceSchema = exports.AIAgentToolChoice = void 0;
+exports.AIAgent = exports.aiAgentOptionsSchema = exports.aiAgentToolChoiceSchema = exports.AIAgentToolChoice = exports.DEFAULT_OUTPUT_KEY = void 0;
 const zod_1 = require("zod");
 const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const template_js_1 = require("../prompt/template.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");
+exports.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(),
@@ -106,12 +108,16 @@ class AIAgent extends agent_js_1.Agent {
             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 || exports.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
      *
@@ -194,7 +204,7 @@ class AIAgent extends agent_js_1.Agent {
             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 });
@@ -254,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 || exports.DEFAULT_OUTPUT_KEY;
         return {
             [outputKey]: error.reason,
         };

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/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 & Message, 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 & Message, 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 & Message, 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 & Message, 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 & Message, 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

@@ -42,6 +42,7 @@ 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;
 }
@@ -77,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 & Message, 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 & Message, options: InvokeOptions & {
         returnActiveAgent: true;
         streaming: true;
     }): Promise<[AgentResponseStream<O>, Promise<Agent>]>;
@@ -91,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 & Message, 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 & Message, 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 & Message, 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>;
@@ -142,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"];
@@ -167,7 +169,7 @@ declare class AIGNEContextShared {
     private timer?;
     private initTimeout;
     get status(): "normal" | "timeout";
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, input: I, context: Context, options?: InvokeOptions): AgentProcessAsyncGenerator<O & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, input: I & Message, context: Context, options?: InvokeOptions): AgentProcessAsyncGenerator<O & {
         __activeAgent__: Agent;
     }>;
     private invokeAgent;

package/lib/cjs/aigne/context.js

@@ -11,7 +11,6 @@ const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.js");
 const types_js_1 = require("../agents/types.js");
 const user_agent_js_1 = require("../agents/user-agent.js");
-const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const event_stream_js_1 = require("../utils/event-stream.js");
 const promise_js_1 = require("../utils/promise.js");
 const stream_utils_js_1 = require("../utils/stream-utils.js");
@@ -87,10 +86,10 @@ class AIGNEContext {
             });
         }
         const newContext = this.newContext();
-        const msg = (0, prompt_builder_js_1.createMessage)(message);
-        return Promise.resolve(newContext.internal.invoke(agent, msg, newContext, options)).then(async (response) => {
+        return Promise.resolve(newContext.internal.invoke(agent, message, newContext, options)).then(async (response) => {
             if (!options?.streaming) {
-                const { __activeAgent__: activeAgent, ...output } = await (0, stream_utils_js_1.agentResponseStreamToObject)(response);
+                let { __activeAgent__: activeAgent, ...output } = await (0, stream_utils_js_1.agentResponseStreamToObject)(response);
+                output = await this.onInvocationResult(output, options);
                 if (options?.returnActiveAgent) {
                     return [output, activeAgent];
                 }
@@ -104,13 +103,14 @@ class AIGNEContext {
                             ...chunk,
                             delta: {
                                 ...chunk.delta,
-                                json: (0, type_utils_js_1.omitBy)(chunk.delta.json, (_, k) => k === "__activeAgent__"),
+                                json: (0, type_utils_js_1.omit)(chunk.delta.json, "__activeAgent__"),
                             },
                         };
                     }
                 },
-                onResult({ __activeAgent__: activeAgent }) {
-                    activeAgentPromise.resolve(activeAgent);
+                onResult: async (output) => {
+                    activeAgentPromise.resolve(output.__activeAgent__);
+                    return await this.onInvocationResult(output, options);
                 },
             });
             const finalStream = !options.returnProgressChunks
@@ -122,6 +122,18 @@ class AIGNEContext {
             return finalStream;
         });
     });
+    async onInvocationResult(output, options) {
+        if (!options?.returnMetadata) {
+            return output;
+        }
+        return {
+            ...output,
+            $meta: {
+                ...output.$meta,
+                usage: this.usage,
+            },
+        };
+    }
     publish = ((topic, payload, options) => {
         if (options?.userContext) {
             Object.assign(this.userContext, options.userContext);
@@ -208,46 +220,54 @@ class AIGNEContextShared {
         return withAbortSignal(this.abortController.signal, new Error("AIGNEContext is timeout"), () => this.invokeAgent(agent, input, context, options));
     }
     async *invokeAgent(agent, input, context, options) {
-        let activeAgent = agent;
-        for (;;) {
-            const result = {};
-            if (options?.sourceAgent && activeAgent !== options.sourceAgent) {
-                options.sourceAgent.hooks.onHandoff?.({
-                    context,
-                    source: options.sourceAgent,
-                    target: activeAgent,
-                    input,
-                });
-            }
-            const stream = await activeAgent.invoke(input, { ...options, context, streaming: true });
-            for await (const value of stream) {
-                if ((0, agent_js_1.isAgentResponseDelta)(value)) {
-                    if (value.delta.json) {
-                        value.delta.json = omitExistsProperties(result, value.delta.json);
-                        Object.assign(result, value.delta.json);
+        const startedAt = Date.now();
+        try {
+            let activeAgent = agent;
+            for (;;) {
+                const result = {};
+                if (options?.sourceAgent && activeAgent !== options.sourceAgent) {
+                    options.sourceAgent.hooks.onHandoff?.({
+                        context,
+                        source: options.sourceAgent,
+                        target: activeAgent,
+                        input,
+                    });
+                }
+                const stream = await activeAgent.invoke(input, { ...options, context, streaming: true });
+                for await (const value of stream) {
+                    if ((0, agent_js_1.isAgentResponseDelta)(value)) {
+                        if (value.delta.json) {
+                            value.delta.json = omitExistsProperties(result, value.delta.json);
+                            Object.assign(result, value.delta.json);
+                        }
+                        delete value.delta.json?.[types_js_1.transferAgentOutputKey];
                     }
-                    delete value.delta.json?.[types_js_1.transferAgentOutputKey];
+                    if ((0, agent_js_1.isEmptyChunk)(value))
+                        continue;
+                    yield value;
                 }
-                if ((0, agent_js_1.isEmptyChunk)(value))
-                    continue;
-                yield value;
-            }
-            if (!options?.disableTransfer) {
-                const transferToAgent = (0, types_js_1.isTransferAgentOutput)(result)
-                    ? result[types_js_1.transferAgentOutputKey].agent
-                    : undefined;
-                if (transferToAgent) {
-                    activeAgent = transferToAgent;
-                    continue;
+                if (!options?.disableTransfer) {
+                    const transferToAgent = (0, types_js_1.isTransferAgentOutput)(result)
+                        ? result[types_js_1.transferAgentOutputKey].agent
+                        : undefined;
+                    if (transferToAgent) {
+                        activeAgent = transferToAgent;
+                        continue;
+                    }
                 }
+                break;
             }
-            break;
+            yield {
+                delta: {
+                    json: { __activeAgent__: activeAgent },
+                },
+            };
+        }
+        finally {
+            const endedAt = Date.now();
+            const duration = endedAt - startedAt;
+            this.usage.duration += duration;
         }
-        yield {
-            delta: {
-                json: { __activeAgent__: activeAgent },
-            },
-        };
     }
 }
 function omitExistsProperties(result, { ...delta }) {

package/lib/cjs/aigne/message-queue.d.ts

@@ -21,7 +21,7 @@ export interface MessagePayload {
 /**
  * @hidden
  */
-export declare function toMessagePayload(payload: Omit<MessagePayload, "context"> | string | Message, options?: Partial<Pick<MessagePayload, "role" | "source">>): Omit<MessagePayload, "context">;
+export declare function toMessagePayload(payload: Omit<MessagePayload, "context"> | Message, options?: Partial<Pick<MessagePayload, "role" | "source">>): Omit<MessagePayload, "context">;
 /**
  * @hidden
  */

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

@@ -4,7 +4,6 @@ exports.MessageQueue = exports.UserOutputTopic = exports.UserInputTopic = void 0
 exports.toMessagePayload = toMessagePayload;
 const strict_event_emitter_1 = require("strict-event-emitter");
 const zod_1 = require("zod");
-const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 /**
  * @hidden
@@ -28,12 +27,12 @@ function isMessagePayload(payload) {
  */
 function toMessagePayload(payload, options) {
     if (isMessagePayload(payload)) {
-        return { ...payload, message: (0, prompt_builder_js_1.createMessage)(payload.message), ...options };
+        return { ...payload, ...options };
     }
     return {
         role: options?.role || "user",
         source: options?.source,
-        message: (0, prompt_builder_js_1.createMessage)(payload),
+        message: payload,
     };
 }
 /**

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

@@ -5,6 +5,7 @@ export interface ContextUsage {
     inputTokens: number;
     outputTokens: number;
     agentCalls: number;
+    duration: number;
 }
 /**
  * @hidden

package/lib/cjs/aigne/usage.js

@@ -9,5 +9,6 @@ function newEmptyContextUsage() {
         inputTokens: 0,
         outputTokens: 0,
         agentCalls: 0,
+        duration: 0,
     };
 }