@aigne/core 1.72.0-beta.2 → 1.72.0-beta.23

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

@@ -1,8 +1,11 @@
 import { z } from "zod";
+import { getNestAgentSchema } from "../loader/agent-yaml.js";
+import { camelizeSchema, getInstructionsSchema, instructionsToPromptBuilder, optionalize, } from "../loader/schema.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { STRUCTURED_STREAM_INSTRUCTIONS } from "../prompt/prompts/structured-stream-instructions.js";
-import { AgentMessageTemplate, ToolMessageTemplate } from "../prompt/template.js";
+import { AgentSkill } from "../prompt/skills/afs/agent-skill/agent-skill.js";
 import * as fastq from "../utils/queue.js";
+import { mergeAgentResponseChunk } from "../utils/stream-utils.js";
 import { ExtractMetadataTransform } from "../utils/structured-stream-extractor.js";
 import { checkArguments, isEmpty } from "../utils/type-utils.js";
 import { Agent, agentOptionsSchema, isAgentResponseDelta, } from "./agent.js";
@@ -84,6 +87,91 @@ export const aiAgentOptionsSchema = agentOptionsSchema.extend({
  */
 export class AIAgent extends Agent {
     tag = "AIAgent";
+    static schema({ filepath }) {
+        const instructionsSchema = getInstructionsSchema({ filepath });
+        const nestAgentSchema = getNestAgentSchema({ filepath });
+        const schema = camelizeSchema(z.object({
+            instructions: optionalize(instructionsSchema),
+            inputKey: optionalize(z.string()),
+            outputKey: optionalize(z.string()),
+            inputFileKey: optionalize(z.string()),
+            outputFileKey: optionalize(z.string()),
+            toolChoice: optionalize(z.nativeEnum(AIAgentToolChoice)),
+            toolCallsConcurrency: optionalize(z.number().int().min(0)),
+            keepTextInToolUses: optionalize(z.boolean()),
+            catchToolsError: optionalize(z.boolean()),
+            structuredStreamMode: optionalize(z.boolean()),
+            session: optionalize(camelizeSchema(z.object({
+                mode: optionalize(z.enum(["auto", "disabled"])),
+                sessionMemory: optionalize(camelizeSchema(z.object({
+                    mode: optionalize(z.enum(["auto", "disabled"])),
+                    memoryRatio: optionalize(z.number().min(0).max(1)),
+                    queryLimit: optionalize(z.number().int().min(0)),
+                    async: optionalize(z.boolean()),
+                    extractor: optionalize(nestAgentSchema),
+                }))),
+                userMemory: optionalize(camelizeSchema(z.object({
+                    mode: optionalize(z.enum(["auto", "disabled"])),
+                    memoryRatio: optionalize(z.number().min(0).max(1)),
+                    queryLimit: optionalize(z.number().int().min(0)),
+                    async: optionalize(z.boolean()),
+                    extractor: optionalize(nestAgentSchema),
+                }))),
+                compact: optionalize(camelizeSchema(z.object({
+                    mode: optionalize(z.enum(["auto", "disabled"])),
+                    maxTokens: z.number().int().min(0).optional(),
+                    keepRecentRatio: optionalize(z.number().min(0).max(1)),
+                    async: optionalize(z.boolean()),
+                    compactor: optionalize(nestAgentSchema),
+                }))),
+            }))),
+        }));
+        return schema;
+    }
+    static async load(options) {
+        const schema = AIAgent.schema(options);
+        const valid = await schema.parseAsync(options.parsed);
+        // Load nested agents from session config if present
+        const sessionCompactor = valid.session?.compact?.compactor
+            ? await options.options?.loadNestAgent(options.filepath, valid.session.compact.compactor, options.options)
+            : undefined;
+        const sessionMemoryExtractor = valid.session?.sessionMemory?.extractor
+            ? await options.options?.loadNestAgent(options.filepath, valid.session.sessionMemory.extractor, options.options)
+            : undefined;
+        const userMemoryExtractor = valid.session?.userMemory?.extractor
+            ? await options.options?.loadNestAgent(options.filepath, valid.session.userMemory.extractor, options.options)
+            : undefined;
+        // Build session configuration with loaded agents
+        const sessionConfig = valid.session
+            ? {
+                ...valid.session,
+                compact: valid.session.compact
+                    ? {
+                        ...valid.session.compact,
+                        compactor: sessionCompactor,
+                    }
+                    : undefined,
+                sessionMemory: valid.session.sessionMemory
+                    ? {
+                        ...valid.session.sessionMemory,
+                        extractor: sessionMemoryExtractor,
+                    }
+                    : undefined,
+                userMemory: valid.session.userMemory
+                    ? {
+                        ...valid.session.userMemory,
+                        extractor: userMemoryExtractor,
+                    }
+                    : undefined,
+            }
+            : undefined;
+        return new AIAgent({
+            ...options.parsed,
+            ...valid,
+            instructions: valid.instructions && instructionsToPromptBuilder(valid.instructions),
+            session: sessionConfig,
+        });
+    }
     /**
      * Create an AIAgent with the specified options
      *
@@ -111,8 +199,6 @@ export class AIAgent extends Agent {
             typeof options.instructions === "string"
                 ? PromptBuilder.from(options.instructions)
                 : (options.instructions ?? new PromptBuilder());
-        this.autoReorderSystemMessages = options.autoReorderSystemMessages ?? true;
-        this.autoMergeSystemMessages = options.autoMergeSystemMessages ?? true;
         this.inputKey = options.inputKey;
         this.inputFileKey = options.inputFileKey;
         this.outputKey = options.outputKey || DEFAULT_OUTPUT_KEY;
@@ -124,6 +210,7 @@ export class AIAgent extends Agent {
         this.memoryAgentsAsTools = options.memoryAgentsAsTools;
         this.memoryPromptTemplate = options.memoryPromptTemplate;
         this.useMemoriesFromContext = options.useMemoriesFromContext;
+        this.session = options.session;
         if (typeof options.catchToolsError === "boolean")
             this.catchToolsError = options.catchToolsError;
         this.structuredStreamMode = options.structuredStreamMode;
@@ -149,8 +236,6 @@ export class AIAgent extends Agent {
      * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-prompt-builder}
      */
     instructions;
-    autoReorderSystemMessages;
-    autoMergeSystemMessages;
     /**
      * Pick a message from input to use as the user's message
      */
@@ -241,6 +326,10 @@ export class AIAgent extends Agent {
      * which outputs structured data in YAML format within <metadata> tags.
      */
     customStructuredStreamInstructions;
+    /**
+     * Agent session configuration
+     */
+    session;
     get inputSchema() {
         let schema = super.inputSchema;
         if (this.inputKey) {
@@ -267,7 +356,7 @@ export class AIAgent extends Agent {
         const model = this.model || options.model || options.context.model;
         if (!model)
             throw new Error("model is required to run AIAgent");
-        const { toolAgents, ...modelInput } = await this.instructions.build({
+        const { toolAgents, session, userMessage, ...modelInput } = await this.instructions.build({
             ...options,
             agent: this,
             input,
@@ -276,25 +365,35 @@ export class AIAgent extends Agent {
         modelInput.modelOptions = await model.getModelOptions(input, options);
         const toolsMap = new Map(toolAgents?.map((i) => [i.name, i]));
         if (this.toolChoice === "router") {
-            return yield* this._processRouter(input, model, modelInput, options, toolsMap);
+            return yield* this._processRouter(input, model, { messages: [...(await session.getMessages()), userMessage], ...modelInput }, options, toolsMap);
+        }
+        const inputMessage = this.inputKey ? input[this.inputKey] : undefined;
+        if (inputMessage) {
+            yield {
+                progress: {
+                    event: "message",
+                    message: { role: "user", content: [{ type: "text", text: inputMessage }] },
+                },
+            };
         }
-        const toolCallMessages = [];
+        await session.startMessage(input, userMessage, options);
+        // const toolCallMessages: ChatModelInputMessage[] = [];
         const outputKey = this.outputKey;
         for (;;) {
             const modelOutput = {};
-            let stream = await this.invokeChildAgent(model, { ...modelInput, messages: modelInput.messages.concat(toolCallMessages) }, { ...options, streaming: true });
+            let stream = await this.invokeChildAgent(model, { messages: await session.getMessages(), ...modelInput }, { ...options, streaming: true });
             if (this.structuredStreamMode) {
                 const { metadataStart, metadataEnd, parse } = this.customStructuredStreamInstructions || STRUCTURED_STREAM_INSTRUCTIONS;
                 stream = stream.pipeThrough(new ExtractMetadataTransform({ start: metadataStart, end: metadataEnd, parse }));
             }
             let isTextIgnored = false;
             for await (const value of stream) {
+                mergeAgentResponseChunk(modelOutput, value);
                 if (isAgentResponseDelta(value)) {
                     if (!isTextIgnored && value.delta.text?.text) {
                         yield { delta: { text: { [outputKey]: value.delta.text.text } } };
                     }
                     if (value.delta.json) {
-                        Object.assign(modelOutput, value.delta.json);
                         if (this.structuredStreamMode) {
                             yield { delta: { json: value.delta.json.json } };
                             if (!isTextIgnored && modelOutput.json && this.ignoreTextOfStructuredStreamMode) {
@@ -304,14 +403,39 @@ export class AIAgent extends Agent {
                     }
                 }
             }
-            const { toolCalls, json, text, files } = modelOutput;
-            if (toolCalls?.length) {
+            const { toolCalls, json, text, thoughts, files } = modelOutput;
+            if (text || thoughts) {
+                const content = [];
+                if (thoughts) {
+                    content.push({ type: "text", text: thoughts, isThinking: true });
+                }
+                if (text) {
+                    content.push({ type: "text", text });
+                }
+                if (content.length) {
+                    const message = { role: "agent", content };
+                    yield { progress: { event: "message", message } };
+                    await session.appendCurrentMessages(message, options);
+                }
+            }
+            const toolCallsWithTools = toolCalls?.map((call) => {
+                const tool = toolsMap.get(call.function.name);
+                if (!tool)
+                    throw new Error(`Tool not found: ${call.function.name}`);
+                return {
+                    ...call,
+                    tool,
+                };
+            });
+            if (toolCallsWithTools?.length) {
                 if (this.keepTextInToolUses !== true) {
                     yield { delta: { json: { [outputKey]: "" } } };
                 }
                 else {
-                    yield { delta: { text: { [outputKey]: "\n" } } };
+                    yield { delta: { text: { [outputKey]: "\n\n" } } };
                 }
+                const toolCallMessage = { role: "agent", toolCalls };
+                yield { progress: { event: "message", message: toolCallMessage } };
                 const executedToolCalls = [];
                 let error;
                 const queue = fastq.promise(async ({ tool, call }) => {
@@ -328,7 +452,7 @@ export class AIAgent extends Agent {
                                 },
                             };
                         });
-                        executedToolCalls.push({ call, output });
+                        executedToolCalls.push({ call, tool, output });
                     }
                     catch (e) {
                         error = e;
@@ -336,21 +460,30 @@ export class AIAgent extends Agent {
                     }
                 }, this.toolCallsConcurrency || 1);
                 // Execute tools
-                for (const call of toolCalls) {
-                    const tool = toolsMap.get(call.function.name);
-                    if (!tool)
-                        throw new Error(`Tool not found: ${call.function.name}`);
-                    queue.push({ tool, call });
+                for (const call of toolCallsWithTools) {
+                    queue.push({ tool: call.tool, call });
                 }
                 await queue.drained();
                 if (error)
                     throw error;
+                const toolResultMessages = [];
                 // Continue LLM function calling loop if any tools were executed
                 if (executedToolCalls.length) {
+                    for (const { call, tool, output } of executedToolCalls) {
+                        const isAgentSkill = !output.isError && tool instanceof AgentSkill ? true : undefined;
+                        const text = await tool.formatOutput(output);
+                        const message = {
+                            role: "tool",
+                            toolCallId: call.id,
+                            content: [{ type: "text", text, isAgentSkill }],
+                        };
+                        yield { progress: { event: "message", message: message } };
+                        toolResultMessages.push(message);
+                    }
                     const transferOutput = executedToolCalls.find((i) => isTransferAgentOutput(i.output))?.output;
                     if (transferOutput)
                         return transferOutput;
-                    toolCallMessages.push(await AgentMessageTemplate.from(undefined, executedToolCalls.map(({ call }) => call)).format(), ...(await Promise.all(executedToolCalls.map(({ call, output }) => ToolMessageTemplate.from(output, call.id).format()))));
+                    await session.appendCurrentMessages([toolCallMessage, ...toolResultMessages], options);
                     continue;
                 }
             }
@@ -367,6 +500,7 @@ export class AIAgent extends Agent {
             if (!isEmpty(result)) {
                 yield { delta: { json: result } };
             }
+            await session.endMessage(result, undefined, options);
             return;
         }
     }

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

@@ -57,7 +57,9 @@ export declare abstract class ChatModel extends Model<ChatModelInput, ChatModelO
     getModelCapabilities(): {
         supportsParallelToolCalls: boolean;
     };
+    getModelOptions(input: Message, options: AgentInvokeOptions): Promise<ChatModelInputOptions>;
     private validateToolNames;
+    countTokens(input: ChatModelInput): Promise<number>;
     /**
      * Normalizes tool names to ensure compatibility with language models
      *
@@ -203,6 +205,13 @@ export interface ChatModelInputMessage {
      * Name of the message sender (for multi-agent scenarios)
      */
     name?: string;
+    /**
+     * Cache control marker for the entire message (only supported by Claude)
+     *
+     * This is syntactic sugar that applies cacheControl to the last content block
+     * of the message. See {@link CacheControl} for details.
+     */
+    cacheControl?: CacheControl;
 }
 /**
  * Type of input message content
@@ -218,27 +227,66 @@ export type ChatModelInputMessageContent = string | UnionContent[];
 export type TextContent = {
     type: "text";
     text: string;
+    isThinking?: boolean;
+    isAgentSkill?: boolean;
+    /**
+     * Cache control marker (only supported by Claude)
+     *
+     * When set, this content block will be marked as a cache breakpoint.
+     * See {@link CacheControl} for details.
+     */
+    cacheControl?: CacheControl;
 };
 export declare const textContentSchema: z.ZodObject<{
     type: z.ZodLiteral<"text">;
     text: z.ZodString;
+    cacheControl: ZodType<{
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined, z.ZodTypeDef, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined>;
 }, "strip", z.ZodTypeAny, {
     type: "text";
     text: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     type: "text";
     text: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>;
 export type UnionContent = TextContent | FileUnionContent;
 export declare const unionContentSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     type: z.ZodLiteral<"text">;
     text: z.ZodString;
+    cacheControl: ZodType<{
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined, z.ZodTypeDef, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined>;
 }, "strip", z.ZodTypeAny, {
     type: "text";
     text: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     type: "text";
     text: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     filename: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
     mimeType: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
@@ -340,6 +388,14 @@ export interface ChatModelInputTool {
      * For example, Gemini's thought_signature
      */
     metadata?: Record<string, any>;
+    /**
+     * Cache control marker (only supported by Claude)
+     *
+     * When set, this tool definition will be marked as a cache breakpoint.
+     * Typically applied to the last tool in the tools array.
+     * See {@link CacheControl} for details.
+     */
+    cacheControl?: CacheControl;
 }
 /**
  * Tool selection strategy
@@ -362,6 +418,82 @@ export type ChatModelInputToolChoice = "auto" | "none" | "required" | {
     };
 };
 export type Modality = "text" | "image" | "audio";
+/**
+ * Cache control marker for prompt caching
+ *
+ * Used to mark content blocks, messages, or tools for caching.
+ * Currently only supported by Anthropic (Claude) models.
+ */
+export interface CacheControl {
+    /**
+     * Cache type (currently only "ephemeral" is supported)
+     */
+    type: "ephemeral";
+    /**
+     * Cache TTL (Time To Live)
+     * - "5m": 5 minutes (default)
+     * - "1h": 1 hour
+     */
+    ttl?: "5m" | "1h";
+}
+/**
+ * Cache configuration options
+ *
+ * Controls how prompt caching is used for supported providers.
+ * Prompt caching can significantly reduce costs and latency by reusing
+ * previously processed prompts (system messages, tool definitions, etc.).
+ */
+export interface CacheConfig {
+    /**
+     * Whether to enable prompt caching
+     *
+     * - OpenAI: Ignored (always enabled automatically)
+     * - Gemini: Controls explicit caching
+     * - Claude: Controls whether to add cache_control markers
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Cache TTL (Time To Live)
+     *
+     * - OpenAI: Ignored (automatic)
+     * - Gemini: Supports custom seconds
+     * - Claude: Only supports "5m" or "1h"
+     *
+     * @default "5m"
+     */
+    ttl?: "5m" | "1h" | number;
+    /**
+     * Caching strategy
+     *
+     * - "auto": Automatically add cache breakpoints at optimal locations
+     * - "manual": Require explicit cacheControl markers on messages/tools
+     *
+     * @default "auto"
+     */
+    strategy?: "auto" | "manual";
+    /**
+     * Auto cache breakpoint locations (only effective when strategy="auto")
+     *
+     * @default { tools: true, system: true, lastMessage: false }
+     */
+    autoBreakpoints?: {
+        /** Cache tool definitions */
+        tools?: boolean;
+        /** Cache system messages */
+        system?: boolean;
+        /** Cache last message in conversation history */
+        lastMessage?: boolean;
+    };
+}
+/**
+ * Default cache configuration
+ *
+ * Enables automatic caching for system messages and tool definitions,
+ * which typically provides the best cost/performance tradeoff.
+ */
+export declare const DEFAULT_CACHE_CONFIG: CacheConfig;
 /**
  * Model-specific configuration options
  *
@@ -395,6 +527,15 @@ export interface ChatModelInputOptions extends Record<string, unknown> {
     modalities?: Modality[];
     preferInputFileType?: "file" | "url";
     reasoningEffort?: number | "minimal" | "low" | "medium" | "high";
+    /**
+     * Cache configuration for prompt caching
+     *
+     * Enables caching of system messages, tool definitions, and conversation history
+     * to reduce costs and latency. See {@link CacheConfig} for details.
+     *
+     * @default DEFAULT_CACHE_CONFIG (enabled with auto strategy)
+     */
+    cacheConfig?: CacheConfig;
 }
 export type ChatModelInputOptionsWithGetter = GetterSchema<ChatModelInputOptions>;
 /**
@@ -492,6 +633,16 @@ export interface ChatModelOutputUsage {
      * AIGNE Hub credit usage
      */
     aigneHubCredits?: number;
+    /**
+     * Number of tokens written to cache (first time caching)
+     * Only applicable for providers that support explicit cache creation (e.g., Anthropic)
+     */
+    cacheCreationInputTokens?: number;
+    /**
+     * Number of tokens read from cache (cache hit)
+     * Supported by OpenAI, Anthropic, and Gemini
+     */
+    cacheReadInputTokens?: number;
     /**
      * Credit prefix
      */
@@ -501,15 +652,21 @@ export declare const chatModelOutputUsageSchema: z.ZodObject<{
     inputTokens: z.ZodNumber;
     outputTokens: z.ZodNumber;
     aigneHubCredits: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+    cacheCreationInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+    cacheReadInputTokens: ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
     creditPrefix: ZodType<"$" | "€" | "¥" | undefined, z.ZodTypeDef, "$" | "€" | "¥" | undefined>;
 }, "strip", z.ZodTypeAny, {
     inputTokens: number;
     outputTokens: number;
     aigneHubCredits?: number | undefined;
+    cacheCreationInputTokens?: number | undefined;
+    cacheReadInputTokens?: number | undefined;
     creditPrefix?: "$" | "€" | "¥" | undefined;
 }, {
     inputTokens: number;
     outputTokens: number;
     aigneHubCredits?: number | undefined;
+    cacheCreationInputTokens?: number | undefined;
+    cacheReadInputTokens?: number | undefined;
     creditPrefix?: "$" | "€" | "¥" | undefined;
 }>;

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

@@ -4,6 +4,7 @@ import { convertJsonSchemaToZod } from "zod-from-json-schema";
 import { optionalize } from "../loader/schema.js";
 import { wrapAutoParseJsonSchema } from "../utils/json-schema.js";
 import { logger } from "../utils/logger.js";
+import { estimateTokens } from "../utils/token-estimator.js";
 import { checkArguments, isNil, omitByDeep } from "../utils/type-utils.js";
 import { agentOptionsSchema, getterSchema, } from "./agent.js";
 import { fileContentSchema, fileUnionContentSchema, localContentSchema, Model, urlContentSchema, } from "./model.js";
@@ -80,6 +81,19 @@ export class ChatModel extends Model {
             supportsParallelToolCalls: this.supportsParallelToolCalls,
         };
     }
+    async getModelOptions(input, options) {
+        const modelOptions = (await super.getModelOptions(input, options));
+        return {
+            ...modelOptions,
+            cacheConfig: {
+                ...modelOptions.cacheConfig,
+                autoBreakpoints: {
+                    ...modelOptions.cacheConfig?.autoBreakpoints,
+                    lastMessage: modelOptions.cacheConfig?.autoBreakpoints?.lastMessage ?? true,
+                },
+            },
+        };
+    }
     validateToolNames(tools) {
         for (const tool of tools ?? []) {
             if (!/^[a-zA-Z0-9_]+$/.test(tool.function.name)) {
@@ -87,6 +101,9 @@ export class ChatModel extends Model {
             }
         }
     }
+    async countTokens(input) {
+        return estimateTokens(JSON.stringify(input));
+    }
     /**
      * Normalizes tool names to ensure compatibility with language models
      *
@@ -188,6 +205,10 @@ export class ChatModel extends Model {
             options.context.usage.inputTokens += usage.inputTokens;
             if (usage.aigneHubCredits)
                 options.context.usage.aigneHubCredits += usage.aigneHubCredits;
+            if (usage.cacheCreationInputTokens)
+                options.context.usage.cacheCreationInputTokens += usage.cacheCreationInputTokens;
+            if (usage.cacheReadInputTokens)
+                options.context.usage.cacheReadInputTokens += usage.cacheReadInputTokens;
             if (usage.creditPrefix)
                 options.context.usage.creditPrefix = usage.creditPrefix;
         }
@@ -197,7 +218,7 @@ export class ChatModel extends Model {
             const files = z.array(fileUnionContentSchema).parse(output.files);
             output = {
                 ...output,
-                files: await Promise.all(files.map((file) => this.transformFileType(input.outputFileType, file, options))),
+                files: await Promise.all(files.map((file) => this.transformFileType(input.outputFileType, file))),
             };
         }
         // Remove fields with `null` value for validation
@@ -244,6 +265,10 @@ export const roleSchema = z.union([
 export const textContentSchema = z.object({
     type: z.literal("text"),
     text: z.string(),
+    cacheControl: optionalize(z.object({
+        type: z.literal("ephemeral"),
+        ttl: optionalize(z.union([z.literal("5m"), z.literal("1h")])),
+    })),
 });
 export const unionContentSchema = z.discriminatedUnion("type", [
     textContentSchema,
@@ -265,6 +290,10 @@ const chatModelInputMessageSchema = z.object({
     }))),
     toolCallId: optionalize(z.string()),
     name: optionalize(z.string()),
+    cacheControl: optionalize(z.object({
+        type: z.literal("ephemeral"),
+        ttl: optionalize(z.union([z.literal("5m"), z.literal("1h")])),
+    })),
 });
 const chatModelInputResponseFormatSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("text") }),
@@ -286,6 +315,10 @@ const chatModelInputToolSchema = z.object({
         parameters: z.record(z.string(), z.unknown()),
     }),
     metadata: optionalize(z.record(z.string(), z.unknown())),
+    cacheControl: optionalize(z.object({
+        type: z.literal("ephemeral"),
+        ttl: optionalize(z.union([z.literal("5m"), z.literal("1h")])),
+    })),
 });
 const chatModelInputToolChoiceSchema = z.union([
     z.literal("auto"),
@@ -293,6 +326,22 @@ const chatModelInputToolChoiceSchema = z.union([
     z.literal("required"),
     chatModelInputToolSchema,
 ]);
+/**
+ * Default cache configuration
+ *
+ * Enables automatic caching for system messages and tool definitions,
+ * which typically provides the best cost/performance tradeoff.
+ */
+export const DEFAULT_CACHE_CONFIG = {
+    enabled: true,
+    ttl: "5m",
+    strategy: "auto",
+    autoBreakpoints: {
+        tools: true,
+        system: true,
+        lastMessage: false,
+    },
+};
 const modelOptionsSchemaProperties = {
     model: z.string(),
     temperature: z.number(),
@@ -308,15 +357,29 @@ const modelOptionsSchemaProperties = {
         z.literal("medium"),
         z.literal("high"),
     ]),
+    cacheConfig: z.object({
+        enabled: optionalize(z.boolean().default(true)),
+        ttl: optionalize(z.union([z.literal("5m"), z.literal("1h"), z.number()]).default("5m")),
+        strategy: optionalize(z.union([z.literal("auto"), z.literal("manual")]).default("auto")),
+        autoBreakpoints: optionalize(z.object({
+            tools: optionalize(z.boolean().default(true)),
+            system: optionalize(z.boolean().default(true)),
+            lastMessage: optionalize(z.boolean().default(false)),
+        })),
+    }),
 };
-const modelOptionsSchema = z.object(Object.fromEntries(Object.entries(modelOptionsSchemaProperties).map(([key, schema]) => [
+const modelOptionsSchema = z
+    .object(Object.fromEntries(Object.entries(modelOptionsSchemaProperties).map(([key, schema]) => [
     key,
     optionalize(schema),
-])));
-const modelOptionsWithGetterSchema = z.object(Object.fromEntries(Object.entries(modelOptionsSchemaProperties).map(([key, schema]) => [
+])))
+    .passthrough();
+const modelOptionsWithGetterSchema = z
+    .object(Object.fromEntries(Object.entries(modelOptionsSchemaProperties).map(([key, schema]) => [
     key,
     optionalize(getterSchema(schema)),
-])));
+])))
+    .passthrough();
 const chatModelOptionsSchema = agentOptionsSchema.extend({
     model: optionalize(z.string()),
     modelOptions: optionalize(modelOptionsWithGetterSchema),
@@ -341,6 +404,8 @@ export const chatModelOutputUsageSchema = z.object({
     inputTokens: z.number(),
     outputTokens: z.number(),
     aigneHubCredits: optionalize(z.number()),
+    cacheCreationInputTokens: optionalize(z.number()),
+    cacheReadInputTokens: optionalize(z.number()),
     creditPrefix: optionalize(z.union([z.literal("$"), z.literal("€"), z.literal("¥")])),
 });
 const chatModelOutputSchema = z.object({