@aigne/core 1.63.0 → 1.64.0-beta

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [1.64.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.63.0...core-v1.64.0-beta) (2025-10-21)
+
+
+### Features
+
+* add thinking support to Gemini chat models ([#650](https://github.com/AIGNE-io/aigne-framework/issues/650)) ([09b828b](https://github.com/AIGNE-io/aigne-framework/commit/09b828ba668d90cc6aac68a5e8190adb146b5e45))
+* add user context support to prompt template variables ([#649](https://github.com/AIGNE-io/aigne-framework/issues/649)) ([a02d9b4](https://github.com/AIGNE-io/aigne-framework/commit/a02d9b412878050b8c1e32127b505c0346f19bba))
+* **cli:** add metadata traces including CLI version, app name, and version ([#646](https://github.com/AIGNE-io/aigne-framework/issues/646)) ([c64bd76](https://github.com/AIGNE-io/aigne-framework/commit/c64bd761ba4c9f3854be5feee208c711bff7a170))
+
+
+### Bug Fixes
+
+* **gemini:** handle empty responses when files are present ([#648](https://github.com/AIGNE-io/aigne-framework/issues/648)) ([f4e259c](https://github.com/AIGNE-io/aigne-framework/commit/f4e259c5e5c687c347bb5cf29cbb0b5bf4d0d4a1))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/observability-api bumped to 0.11.3-beta
+
 ## [1.63.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.63.0-beta.12...core-v1.63.0) (2025-10-19)
 
 

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

@@ -407,6 +407,10 @@ export interface ChatModelOutput extends Message {
      * Text format response content
      */
     text?: string;
+    /**
+     * Model's internal thoughts (if supported)
+     */
+    thoughts?: string;
     /**
      * JSON format response content
      */

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

@@ -38,6 +38,7 @@ const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const zod_1 = require("zod");
 const zod_from_json_schema_1 = require("zod-from-json-schema");
 const json_schema_js_1 = require("../utils/json-schema.js");
+const logger_js_1 = require("../utils/logger.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_1 = require("./agent.js");
 const model_js_1 = require("./model.js");
@@ -215,7 +216,10 @@ class ChatModel extends model_js_1.Model {
      */
     async postprocess(input, output, options) {
         super.postprocess(input, output, options);
-        const { usage } = output;
+        const { usage, thoughts, model } = output;
+        if (thoughts) {
+            logger_js_1.logger.info(`Model Thoughts (${model}): ${thoughts}`);
+        }
         if (usage) {
             options.context.usage.outputTokens += usage.outputTokens;
             options.context.usage.inputTokens += usage.inputTokens;
@@ -360,6 +364,7 @@ exports.chatModelOutputUsageSchema = zod_1.z.object({
 });
 const chatModelOutputSchema = zod_1.z.object({
     text: zod_1.z.string().optional(),
+    thoughts: zod_1.z.string().optional(),
     json: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
     toolCalls: zod_1.z.array(chatModelOutputToolCallSchema).optional(),
     usage: exports.chatModelOutputUsageSchema.optional(),

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

@@ -5,6 +5,7 @@ import { type ImageModelOutput } from "./image-model.js";
 import { type FileType } from "./model.js";
 export interface ImageAgentOptions<I extends Message = any, O extends ImageModelOutput = any> extends Omit<AgentOptions<I, O>, "outputSchema"> {
     instructions: string | PromptBuilder;
+    inputFileKey?: string;
     modelOptions?: Record<string, any>;
     outputFileType?: FileType;
 }
@@ -16,6 +17,7 @@ export declare class ImageAgent<I extends Message = any, O extends ImageModelOut
     static from<I extends Message = any, O extends ImageModelOutput = any>(options: ImageAgentOptions<I, O>): ImageAgent<I, O>;
     constructor(options: ImageAgentOptions<I, O>);
     instructions: PromptBuilder;
+    inputFileKey?: string;
     modelOptions?: Record<string, any>;
     outputFileType?: FileType;
     process(input: I, options: AgentInvokeOptions): Promise<O>;

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

@@ -27,18 +27,30 @@ class ImageAgent extends agent_js_1.Agent {
             typeof options.instructions === "string"
                 ? prompt_builder_js_1.PromptBuilder.from(options.instructions)
                 : options.instructions;
+        this.inputFileKey = options.inputFileKey;
         this.modelOptions = options.modelOptions;
         this.outputFileType = options.outputFileType;
     }
     instructions;
+    inputFileKey;
     modelOptions;
     outputFileType;
     async process(input, options) {
         const imageModel = this.imageModel || options.imageModel || options.context.imageModel;
         if (!imageModel)
             throw new Error("image model is required to run ImageAgent");
-        const { prompt } = await this.instructions.buildImagePrompt({ input });
-        return (await this.invokeChildAgent(imageModel, { ...input, modelOptions: this.modelOptions, prompt, outputFileType: this.outputFileType }, { ...options, streaming: false }));
+        const { prompt, image } = await this.instructions.buildImagePrompt({
+            ...options,
+            input,
+            agent: this,
+        });
+        return (await this.invokeChildAgent(imageModel, {
+            ...input,
+            modelOptions: this.modelOptions,
+            prompt,
+            image,
+            outputFileType: this.outputFileType,
+        }, { ...options, streaming: false }));
     }
 }
 exports.ImageAgent = ImageAgent;

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

@@ -6,7 +6,7 @@ import type { UserAgent } from "../agents/user-agent.js";
 import { type LoadOptions } from "../loader/index.js";
 import { AIGNEContext, type Context, type InvokeOptions, type UserContext } from "./context.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
-import type { AIGNECLIAgents } from "./type.js";
+import type { AIGNECLIAgents, AIGNEMetadata } from "./type.js";
 import type { ContextLimits } from "./usage.js";
 /**
  * Options for the AIGNE class.
@@ -53,6 +53,7 @@ export interface AIGNEOptions {
      * Observer for the AIGNE instance.
      */
     observer?: AIGNEObserver;
+    metadata?: AIGNEMetadata;
 }
 /**
  * AIGNE is a class that orchestrates multiple agents to build complex AI applications.
@@ -136,6 +137,10 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * Observer for the AIGNE instance.
      */
     readonly observer?: AIGNEObserver;
+    /**
+     * Metadata for the AIGNE instance.
+     */
+    readonly metadata: AIGNEMetadata;
     /**
      * Adds one or more agents to this AIGNE instance.
      * Each agent is attached to this AIGNE instance, allowing it to access the AIGNE's resources.

package/lib/cjs/aigne/aigne.js

@@ -37,6 +37,7 @@ class AIGNE {
             imageModel,
             agents: agents.concat(options?.agents ?? []),
             skills: skills.concat(options?.skills ?? []),
+            metadata: options?.metadata,
         });
     }
     /**
@@ -66,6 +67,7 @@ class AIGNE {
         this.cli = options?.cli ?? {};
         this.observer?.serve();
         this.initProcessExitHandler();
+        this.metadata = options?.metadata ?? {};
     }
     /**
      * Optional root directory for this AIGNE instance.
@@ -115,6 +117,10 @@ class AIGNE {
      * Observer for the AIGNE instance.
      */
     observer;
+    /**
+     * Metadata for the AIGNE instance.
+     */
+    metadata = {};
     /**
      * Adds one or more agents to this AIGNE instance.
      * Each agent is attached to this AIGNE instance, allowing it to access the AIGNE's resources.

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

@@ -9,6 +9,7 @@ import type { Memory } from "../memory/memory.js";
 import { type OmitPropertiesFromArrayFirstElement } from "../utils/type-utils.js";
 import type { Args, Listener, TypedEventEmitter } from "../utils/typed-event-emitter.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
+import type { AIGNEMetadata } from "./type.js";
 import { type ContextLimits, type ContextUsage } from "./usage.js";
 /**
  * @hidden
@@ -78,6 +79,7 @@ export interface Context<U extends UserContext = UserContext> extends TypedEvent
     skills?: Agent[];
     agents: Agent[];
     observer?: AIGNEObserver;
+    metadata?: AIGNEMetadata;
     span?: Span;
     usage: ContextUsage;
     limits?: ContextLimits;
@@ -187,7 +189,7 @@ export declare class AIGNEContext implements Context {
 }
 declare class AIGNEContextShared {
     private readonly parent?;
-    constructor(parent?: (Pick<Context, "model" | "imageModel" | "agents" | "skills" | "limits" | "observer"> & {
+    constructor(parent?: (Pick<Context, "model" | "imageModel" | "agents" | "skills" | "limits" | "observer" | "metadata"> & {
         messageQueue?: MessageQueue;
         events?: Emitter<any>;
     }) | undefined);
@@ -198,6 +200,7 @@ declare class AIGNEContextShared {
     get skills(): Agent<any, any>[] | undefined;
     get agents(): Agent<any, any>[];
     get observer(): AIGNEObserver | undefined;
+    get metadata(): AIGNEMetadata | undefined;
     get limits(): ContextLimits | undefined;
     usage: ContextUsage;
     userContext: Context["userContext"];

package/lib/cjs/aigne/context.js

@@ -217,6 +217,7 @@ class AIGNEContext {
                     if (this.parentId) {
                         span.setAttribute("custom.parent_id", this.parentId);
                     }
+                    span.setAttribute("metadata", JSON.stringify(this.internal.metadata ?? {}));
                     span.setAttribute("custom.started_at", b.timestamp);
                     span.setAttribute("input", JSON.stringify(input));
                     span.setAttribute("agentTag", agent.tag ?? "UnknownAgent");
@@ -300,6 +301,9 @@ class AIGNEContextShared {
     get observer() {
         return this.parent?.observer;
     }
+    get metadata() {
+        return this.parent?.metadata;
+    }
     get limits() {
         return this.parent?.limits;
     }

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

@@ -10,3 +10,17 @@ export interface AIGNECLIAgent {
     description?: string;
     agents?: AIGNECLIAgent[];
 }
+export interface AIGNEMetadata {
+    /**
+     * CLI version (e.g., "1.51.0")
+     */
+    cliVersion?: string;
+    /**
+     * Application name (e.g., "docsmith", "websmith")
+     */
+    appName?: string;
+    /**
+     * Application version (e.g., "2.3.4")
+     */
+    appVersion?: string;
+}

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

@@ -59,6 +59,7 @@ export interface AIAgentSchema extends BaseAgentSchema {
     inputKey?: string;
     inputFileKey?: string;
     outputKey?: string;
+    outputFileKey?: string;
     toolChoice?: AIAgentToolChoice;
     toolCallsConcurrency?: number;
     keepTextInToolUses?: boolean;
@@ -66,6 +67,7 @@ export interface AIAgentSchema extends BaseAgentSchema {
 export interface ImageAgentSchema extends BaseAgentSchema {
     type: "image";
     instructions: Instructions;
+    inputFileKey?: string;
     modelOptions?: Record<string, any>;
 }
 export interface MCPAgentSchema extends BaseAgentSchema {

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

@@ -128,6 +128,7 @@ async function parseAgentFile(path, data) {
                 .object({
                 type: zod_1.z.literal("image"),
                 instructions: instructionsSchema,
+                inputFileKey: (0, schema_js_1.optionalize)(zod_1.z.string()),
                 modelOptions: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(zod_1.z.record(zod_1.z.any()))),
             })
                 .extend(baseAgentSchema.shape),

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

@@ -2,6 +2,8 @@ import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
 import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
 import { type AIAgent } from "../agents/ai-agent.js";
 import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
+import type { ImageAgent } from "../agents/image-agent.js";
+import { type FileUnionContent } from "../agents/model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
@@ -27,9 +29,13 @@ export declare class PromptBuilder {
     build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;
-    buildImagePrompt(options: Pick<PromptBuildOptions, "input">): Promise<{
+    buildImagePrompt(options: Pick<PromptBuildOptions, "input" | "context"> & {
+        agent: ImageAgent;
+    }): Promise<{
         prompt: string;
+        image?: FileUnionContent[];
     }>;
+    private getTemplateVariables;
     private buildMessages;
     private refineMessages;
     private convertMemoriesToMessages;

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

@@ -78,9 +78,21 @@ class PromptBuilder {
     async buildImagePrompt(options) {
         const messages = (await (typeof this.instructions === "string"
             ? template_js_1.ChatMessagesTemplate.from([template_js_1.SystemMessageTemplate.from(this.instructions)])
-            : this.instructions)?.format(options.input, { workingDir: this.workingDir })) ?? [];
+            : this.instructions)?.format(this.getTemplateVariables(options), { workingDir: this.workingDir })) ?? [];
+        const inputFileKey = options.agent?.inputFileKey;
+        const files = (0, type_utils_js_1.flat)(inputFileKey
+            ? (0, type_utils_js_1.checkArguments)("Check input files", (0, schema_js_1.optionalize)(model_js_1.fileUnionContentsSchema), options.input?.[inputFileKey])
+            : null);
         return {
             prompt: messages.map((i) => i.content).join("\n"),
+            image: files.length ? files : undefined,
+        };
+    }
+    getTemplateVariables(options) {
+        return {
+            userContext: options.context?.userContext,
+            ...options.context?.userContext,
+            ...options.input,
         };
     }
     async buildMessages(options) {
@@ -89,7 +101,7 @@ class PromptBuilder {
         const message = inputKey && typeof input?.[inputKey] === "string" ? input[inputKey] : undefined;
         const [messages, otherCustomMessages] = (0, type_utils_js_1.partition)((await (typeof this.instructions === "string"
             ? template_js_1.ChatMessagesTemplate.from([template_js_1.SystemMessageTemplate.from(this.instructions)])
-            : this.instructions)?.format(options.input, { workingDir: this.workingDir })) ?? [], (i) => i.role === "system");
+            : this.instructions)?.format(this.getTemplateVariables(options), { workingDir: this.workingDir })) ?? [], (i) => i.role === "system");
         const inputFileKey = options.agent?.inputFileKey;
         const files = (0, type_utils_js_1.flat)(inputFileKey
             ? (0, type_utils_js_1.checkArguments)("Check input files", (0, schema_js_1.optionalize)(model_js_1.fileUnionContentsSchema), input?.[inputFileKey])

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

@@ -407,6 +407,10 @@ export interface ChatModelOutput extends Message {
      * Text format response content
      */
     text?: string;
+    /**
+     * Model's internal thoughts (if supported)
+     */
+    thoughts?: string;
     /**
      * JSON format response content
      */

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

@@ -5,6 +5,7 @@ import { type ImageModelOutput } from "./image-model.js";
 import { type FileType } from "./model.js";
 export interface ImageAgentOptions<I extends Message = any, O extends ImageModelOutput = any> extends Omit<AgentOptions<I, O>, "outputSchema"> {
     instructions: string | PromptBuilder;
+    inputFileKey?: string;
     modelOptions?: Record<string, any>;
     outputFileType?: FileType;
 }
@@ -16,6 +17,7 @@ export declare class ImageAgent<I extends Message = any, O extends ImageModelOut
     static from<I extends Message = any, O extends ImageModelOutput = any>(options: ImageAgentOptions<I, O>): ImageAgent<I, O>;
     constructor(options: ImageAgentOptions<I, O>);
     instructions: PromptBuilder;
+    inputFileKey?: string;
     modelOptions?: Record<string, any>;
     outputFileType?: FileType;
     process(input: I, options: AgentInvokeOptions): Promise<O>;

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

@@ -6,7 +6,7 @@ import type { UserAgent } from "../agents/user-agent.js";
 import { type LoadOptions } from "../loader/index.js";
 import { AIGNEContext, type Context, type InvokeOptions, type UserContext } from "./context.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
-import type { AIGNECLIAgents } from "./type.js";
+import type { AIGNECLIAgents, AIGNEMetadata } from "./type.js";
 import type { ContextLimits } from "./usage.js";
 /**
  * Options for the AIGNE class.
@@ -53,6 +53,7 @@ export interface AIGNEOptions {
      * Observer for the AIGNE instance.
      */
     observer?: AIGNEObserver;
+    metadata?: AIGNEMetadata;
 }
 /**
  * AIGNE is a class that orchestrates multiple agents to build complex AI applications.
@@ -136,6 +137,10 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * Observer for the AIGNE instance.
      */
     readonly observer?: AIGNEObserver;
+    /**
+     * Metadata for the AIGNE instance.
+     */
+    readonly metadata: AIGNEMetadata;
     /**
      * Adds one or more agents to this AIGNE instance.
      * Each agent is attached to this AIGNE instance, allowing it to access the AIGNE's resources.

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

@@ -9,6 +9,7 @@ import type { Memory } from "../memory/memory.js";
 import { type OmitPropertiesFromArrayFirstElement } from "../utils/type-utils.js";
 import type { Args, Listener, TypedEventEmitter } from "../utils/typed-event-emitter.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
+import type { AIGNEMetadata } from "./type.js";
 import { type ContextLimits, type ContextUsage } from "./usage.js";
 /**
  * @hidden
@@ -78,6 +79,7 @@ export interface Context<U extends UserContext = UserContext> extends TypedEvent
     skills?: Agent[];
     agents: Agent[];
     observer?: AIGNEObserver;
+    metadata?: AIGNEMetadata;
     span?: Span;
     usage: ContextUsage;
     limits?: ContextLimits;
@@ -187,7 +189,7 @@ export declare class AIGNEContext implements Context {
 }
 declare class AIGNEContextShared {
     private readonly parent?;
-    constructor(parent?: (Pick<Context, "model" | "imageModel" | "agents" | "skills" | "limits" | "observer"> & {
+    constructor(parent?: (Pick<Context, "model" | "imageModel" | "agents" | "skills" | "limits" | "observer" | "metadata"> & {
         messageQueue?: MessageQueue;
         events?: Emitter<any>;
     }) | undefined);
@@ -198,6 +200,7 @@ declare class AIGNEContextShared {
     get skills(): Agent<any, any>[] | undefined;
     get agents(): Agent<any, any>[];
     get observer(): AIGNEObserver | undefined;
+    get metadata(): AIGNEMetadata | undefined;
     get limits(): ContextLimits | undefined;
     usage: ContextUsage;
     userContext: Context["userContext"];

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

@@ -10,3 +10,17 @@ export interface AIGNECLIAgent {
     description?: string;
     agents?: AIGNECLIAgent[];
 }
+export interface AIGNEMetadata {
+    /**
+     * CLI version (e.g., "1.51.0")
+     */
+    cliVersion?: string;
+    /**
+     * Application name (e.g., "docsmith", "websmith")
+     */
+    appName?: string;
+    /**
+     * Application version (e.g., "2.3.4")
+     */
+    appVersion?: string;
+}

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

@@ -59,6 +59,7 @@ export interface AIAgentSchema extends BaseAgentSchema {
     inputKey?: string;
     inputFileKey?: string;
     outputKey?: string;
+    outputFileKey?: string;
     toolChoice?: AIAgentToolChoice;
     toolCallsConcurrency?: number;
     keepTextInToolUses?: boolean;
@@ -66,6 +67,7 @@ export interface AIAgentSchema extends BaseAgentSchema {
 export interface ImageAgentSchema extends BaseAgentSchema {
     type: "image";
     instructions: Instructions;
+    inputFileKey?: string;
     modelOptions?: Record<string, any>;
 }
 export interface MCPAgentSchema extends BaseAgentSchema {

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

@@ -2,6 +2,8 @@ import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
 import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
 import { type AIAgent } from "../agents/ai-agent.js";
 import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
+import type { ImageAgent } from "../agents/image-agent.js";
+import { type FileUnionContent } from "../agents/model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
@@ -27,9 +29,13 @@ export declare class PromptBuilder {
     build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;
-    buildImagePrompt(options: Pick<PromptBuildOptions, "input">): Promise<{
+    buildImagePrompt(options: Pick<PromptBuildOptions, "input" | "context"> & {
+        agent: ImageAgent;
+    }): Promise<{
         prompt: string;
+        image?: FileUnionContent[];
     }>;
+    private getTemplateVariables;
     private buildMessages;
     private refineMessages;
     private convertMemoriesToMessages;

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

@@ -407,6 +407,10 @@ export interface ChatModelOutput extends Message {
      * Text format response content
      */
     text?: string;
+    /**
+     * Model's internal thoughts (if supported)
+     */
+    thoughts?: string;
     /**
      * JSON format response content
      */

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

@@ -2,6 +2,7 @@ import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { z } from "zod";
 import { convertJsonSchemaToZod } from "zod-from-json-schema";
 import { wrapAutoParseJsonSchema } from "../utils/json-schema.js";
+import { logger } from "../utils/logger.js";
 import { checkArguments, isNil, omitByDeep } from "../utils/type-utils.js";
 import { agentOptionsSchema, } from "./agent.js";
 import { fileContentSchema, fileUnionContentSchema, localContentSchema, Model, urlContentSchema, } from "./model.js";
@@ -178,7 +179,10 @@ export class ChatModel extends Model {
      */
     async postprocess(input, output, options) {
         super.postprocess(input, output, options);
-        const { usage } = output;
+        const { usage, thoughts, model } = output;
+        if (thoughts) {
+            logger.info(`Model Thoughts (${model}): ${thoughts}`);
+        }
         if (usage) {
             options.context.usage.outputTokens += usage.outputTokens;
             options.context.usage.inputTokens += usage.inputTokens;
@@ -322,6 +326,7 @@ export const chatModelOutputUsageSchema = z.object({
 });
 const chatModelOutputSchema = z.object({
     text: z.string().optional(),
+    thoughts: z.string().optional(),
     json: z.record(z.string(), z.unknown()).optional(),
     toolCalls: z.array(chatModelOutputToolCallSchema).optional(),
     usage: chatModelOutputUsageSchema.optional(),

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

@@ -5,6 +5,7 @@ import { type ImageModelOutput } from "./image-model.js";
 import { type FileType } from "./model.js";
 export interface ImageAgentOptions<I extends Message = any, O extends ImageModelOutput = any> extends Omit<AgentOptions<I, O>, "outputSchema"> {
     instructions: string | PromptBuilder;
+    inputFileKey?: string;
     modelOptions?: Record<string, any>;
     outputFileType?: FileType;
 }
@@ -16,6 +17,7 @@ export declare class ImageAgent<I extends Message = any, O extends ImageModelOut
     static from<I extends Message = any, O extends ImageModelOutput = any>(options: ImageAgentOptions<I, O>): ImageAgent<I, O>;
     constructor(options: ImageAgentOptions<I, O>);
     instructions: PromptBuilder;
+    inputFileKey?: string;
     modelOptions?: Record<string, any>;
     outputFileType?: FileType;
     process(input: I, options: AgentInvokeOptions): Promise<O>;

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

@@ -21,17 +21,29 @@ export class ImageAgent extends Agent {
             typeof options.instructions === "string"
                 ? PromptBuilder.from(options.instructions)
                 : options.instructions;
+        this.inputFileKey = options.inputFileKey;
         this.modelOptions = options.modelOptions;
         this.outputFileType = options.outputFileType;
     }
     instructions;
+    inputFileKey;
     modelOptions;
     outputFileType;
     async process(input, options) {
         const imageModel = this.imageModel || options.imageModel || options.context.imageModel;
         if (!imageModel)
             throw new Error("image model is required to run ImageAgent");
-        const { prompt } = await this.instructions.buildImagePrompt({ input });
-        return (await this.invokeChildAgent(imageModel, { ...input, modelOptions: this.modelOptions, prompt, outputFileType: this.outputFileType }, { ...options, streaming: false }));
+        const { prompt, image } = await this.instructions.buildImagePrompt({
+            ...options,
+            input,
+            agent: this,
+        });
+        return (await this.invokeChildAgent(imageModel, {
+            ...input,
+            modelOptions: this.modelOptions,
+            prompt,
+            image,
+            outputFileType: this.outputFileType,
+        }, { ...options, streaming: false }));
     }
 }

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

@@ -6,7 +6,7 @@ import type { UserAgent } from "../agents/user-agent.js";
 import { type LoadOptions } from "../loader/index.js";
 import { AIGNEContext, type Context, type InvokeOptions, type UserContext } from "./context.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
-import type { AIGNECLIAgents } from "./type.js";
+import type { AIGNECLIAgents, AIGNEMetadata } from "./type.js";
 import type { ContextLimits } from "./usage.js";
 /**
  * Options for the AIGNE class.
@@ -53,6 +53,7 @@ export interface AIGNEOptions {
      * Observer for the AIGNE instance.
      */
     observer?: AIGNEObserver;
+    metadata?: AIGNEMetadata;
 }
 /**
  * AIGNE is a class that orchestrates multiple agents to build complex AI applications.
@@ -136,6 +137,10 @@ export declare class AIGNE<U extends UserContext = UserContext> {
      * Observer for the AIGNE instance.
      */
     readonly observer?: AIGNEObserver;
+    /**
+     * Metadata for the AIGNE instance.
+     */
+    readonly metadata: AIGNEMetadata;
     /**
      * Adds one or more agents to this AIGNE instance.
      * Each agent is attached to this AIGNE instance, allowing it to access the AIGNE's resources.

package/lib/esm/aigne/aigne.js

@@ -34,6 +34,7 @@ export class AIGNE {
             imageModel,
             agents: agents.concat(options?.agents ?? []),
             skills: skills.concat(options?.skills ?? []),
+            metadata: options?.metadata,
         });
     }
     /**
@@ -63,6 +64,7 @@ export class AIGNE {
         this.cli = options?.cli ?? {};
         this.observer?.serve();
         this.initProcessExitHandler();
+        this.metadata = options?.metadata ?? {};
     }
     /**
      * Optional root directory for this AIGNE instance.
@@ -112,6 +114,10 @@ export class AIGNE {
      * Observer for the AIGNE instance.
      */
     observer;
+    /**
+     * Metadata for the AIGNE instance.
+     */
+    metadata = {};
     /**
      * Adds one or more agents to this AIGNE instance.
      * Each agent is attached to this AIGNE instance, allowing it to access the AIGNE's resources.

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

@@ -9,6 +9,7 @@ import type { Memory } from "../memory/memory.js";
 import { type OmitPropertiesFromArrayFirstElement } from "../utils/type-utils.js";
 import type { Args, Listener, TypedEventEmitter } from "../utils/typed-event-emitter.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
+import type { AIGNEMetadata } from "./type.js";
 import { type ContextLimits, type ContextUsage } from "./usage.js";
 /**
  * @hidden
@@ -78,6 +79,7 @@ export interface Context<U extends UserContext = UserContext> extends TypedEvent
     skills?: Agent[];
     agents: Agent[];
     observer?: AIGNEObserver;
+    metadata?: AIGNEMetadata;
     span?: Span;
     usage: ContextUsage;
     limits?: ContextLimits;
@@ -187,7 +189,7 @@ export declare class AIGNEContext implements Context {
 }
 declare class AIGNEContextShared {
     private readonly parent?;
-    constructor(parent?: (Pick<Context, "model" | "imageModel" | "agents" | "skills" | "limits" | "observer"> & {
+    constructor(parent?: (Pick<Context, "model" | "imageModel" | "agents" | "skills" | "limits" | "observer" | "metadata"> & {
         messageQueue?: MessageQueue;
         events?: Emitter<any>;
     }) | undefined);
@@ -198,6 +200,7 @@ declare class AIGNEContextShared {
     get skills(): Agent<any, any>[] | undefined;
     get agents(): Agent<any, any>[];
     get observer(): AIGNEObserver | undefined;
+    get metadata(): AIGNEMetadata | undefined;
     get limits(): ContextLimits | undefined;
     usage: ContextUsage;
     userContext: Context["userContext"];

package/lib/esm/aigne/context.js

@@ -211,6 +211,7 @@ export class AIGNEContext {
                     if (this.parentId) {
                         span.setAttribute("custom.parent_id", this.parentId);
                     }
+                    span.setAttribute("metadata", JSON.stringify(this.internal.metadata ?? {}));
                     span.setAttribute("custom.started_at", b.timestamp);
                     span.setAttribute("input", JSON.stringify(input));
                     span.setAttribute("agentTag", agent.tag ?? "UnknownAgent");
@@ -293,6 +294,9 @@ class AIGNEContextShared {
     get observer() {
         return this.parent?.observer;
     }
+    get metadata() {
+        return this.parent?.metadata;
+    }
     get limits() {
         return this.parent?.limits;
     }

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

@@ -10,3 +10,17 @@ export interface AIGNECLIAgent {
     description?: string;
     agents?: AIGNECLIAgent[];
 }
+export interface AIGNEMetadata {
+    /**
+     * CLI version (e.g., "1.51.0")
+     */
+    cliVersion?: string;
+    /**
+     * Application name (e.g., "docsmith", "websmith")
+     */
+    appName?: string;
+    /**
+     * Application version (e.g., "2.3.4")
+     */
+    appVersion?: string;
+}

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

@@ -59,6 +59,7 @@ export interface AIAgentSchema extends BaseAgentSchema {
     inputKey?: string;
     inputFileKey?: string;
     outputKey?: string;
+    outputFileKey?: string;
     toolChoice?: AIAgentToolChoice;
     toolCallsConcurrency?: number;
     keepTextInToolUses?: boolean;
@@ -66,6 +67,7 @@ export interface AIAgentSchema extends BaseAgentSchema {
 export interface ImageAgentSchema extends BaseAgentSchema {
     type: "image";
     instructions: Instructions;
+    inputFileKey?: string;
     modelOptions?: Record<string, any>;
 }
 export interface MCPAgentSchema extends BaseAgentSchema {

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

@@ -124,6 +124,7 @@ export async function parseAgentFile(path, data) {
                 .object({
                 type: z.literal("image"),
                 instructions: instructionsSchema,
+                inputFileKey: optionalize(z.string()),
                 modelOptions: optionalize(camelizeSchema(z.record(z.any()))),
             })
                 .extend(baseAgentSchema.shape),

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

@@ -2,6 +2,8 @@ import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
 import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
 import { type AIAgent } from "../agents/ai-agent.js";
 import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
+import type { ImageAgent } from "../agents/image-agent.js";
+import { type FileUnionContent } from "../agents/model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
@@ -27,9 +29,13 @@ export declare class PromptBuilder {
     build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;
-    buildImagePrompt(options: Pick<PromptBuildOptions, "input">): Promise<{
+    buildImagePrompt(options: Pick<PromptBuildOptions, "input" | "context"> & {
+        agent: ImageAgent;
+    }): Promise<{
         prompt: string;
+        image?: FileUnionContent[];
     }>;
+    private getTemplateVariables;
     private buildMessages;
     private refineMessages;
     private convertMemoriesToMessages;

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

@@ -75,9 +75,21 @@ export class PromptBuilder {
     async buildImagePrompt(options) {
         const messages = (await (typeof this.instructions === "string"
             ? ChatMessagesTemplate.from([SystemMessageTemplate.from(this.instructions)])
-            : this.instructions)?.format(options.input, { workingDir: this.workingDir })) ?? [];
+            : this.instructions)?.format(this.getTemplateVariables(options), { workingDir: this.workingDir })) ?? [];
+        const inputFileKey = options.agent?.inputFileKey;
+        const files = flat(inputFileKey
+            ? checkArguments("Check input files", optionalize(fileUnionContentsSchema), options.input?.[inputFileKey])
+            : null);
         return {
             prompt: messages.map((i) => i.content).join("\n"),
+            image: files.length ? files : undefined,
+        };
+    }
+    getTemplateVariables(options) {
+        return {
+            userContext: options.context?.userContext,
+            ...options.context?.userContext,
+            ...options.input,
         };
     }
     async buildMessages(options) {
@@ -86,7 +98,7 @@ export class PromptBuilder {
         const message = inputKey && typeof input?.[inputKey] === "string" ? input[inputKey] : undefined;
         const [messages, otherCustomMessages] = partition((await (typeof this.instructions === "string"
             ? ChatMessagesTemplate.from([SystemMessageTemplate.from(this.instructions)])
-            : this.instructions)?.format(options.input, { workingDir: this.workingDir })) ?? [], (i) => i.role === "system");
+            : this.instructions)?.format(this.getTemplateVariables(options), { workingDir: this.workingDir })) ?? [], (i) => i.role === "system");
         const inputFileKey = options.agent?.inputFileKey;
         const files = flat(inputFileKey
             ? checkArguments("Check input files", optionalize(fileUnionContentsSchema), input?.[inputFileKey])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.63.0",
+  "version": "1.64.0-beta",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -91,9 +91,9 @@
     "zod": "^3.25.67",
     "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/afs": "^1.1.0",
-    "@aigne/observability-api": "^0.11.2",
-    "@aigne/platform-helpers": "^0.6.3"
+    "@aigne/observability-api": "^0.11.3-beta",
+    "@aigne/platform-helpers": "^0.6.3",
+    "@aigne/afs": "^1.1.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",