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

package/lib/dts/prompt/template.d.ts

@@ -27,35 +27,38 @@ export declare class ChatMessageTemplate {
     content?: ChatModelInputMessage["content"];
     name?: string | undefined;
     options?: FormatOptions | undefined;
-    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined);
+    cacheControl?: ChatModelInputMessage["cacheControl"];
+    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content: string, name?: string, options?: FormatOptions): SystemMessageTemplate;
+    static from(content: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): SystemMessageTemplate;
 }
 export declare class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions): UserMessageTemplate;
+    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): UserMessageTemplate;
 }
 export declare class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls?: ChatModelOutputToolCall[] | undefined;
-    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions): AgentMessageTemplate;
-    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions);
+    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): AgentMessageTemplate;
+    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(_variables?: Record<string, unknown>, _options?: FormatOptions): Promise<{
-        role: "agent" | "system" | "user" | "tool";
+        role: "agent" | "user" | "system" | "tool";
         name: string | undefined;
         content: ChatModelInputMessageContent | undefined;
         toolCalls: ChatModelOutputToolCall[] | undefined;
+        cacheControl: import("../index.js").CacheControl | undefined;
     }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId: string;
-    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions): ToolMessageTemplate;
-    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions);
+    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]): ToolMessageTemplate;
+    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions, cacheControl?: ChatModelInputMessage["cacheControl"]);
     format(_variables?: Record<string, unknown>, _options?: FormatOptions): Promise<{
-        role: "agent" | "system" | "user" | "tool";
+        role: "agent" | "user" | "system" | "tool";
         name: string | undefined;
         content: ChatModelInputMessageContent | undefined;
         toolCallId: string;
+        cacheControl: import("../index.js").CacheControl | undefined;
     }>;
 }
 export declare class ChatMessagesTemplate {
@@ -69,26 +72,62 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
     role: z.ZodLiteral<"system">;
     content: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "system";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "system";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"user">;
     content: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "user";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "user";
     content: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>, z.ZodObject<{
     role: z.ZodLiteral<"agent">;
     content: z.ZodOptional<z.ZodString>;
@@ -121,10 +160,24 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
         id: string;
     }>, "many">>;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "agent";
     name?: string | undefined;
     content?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     toolCalls?: {
         function: {
             name: string;
@@ -137,6 +190,10 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
     role: "agent";
     name?: string | undefined;
     content?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
     toolCalls?: {
         function: {
             name: string;
@@ -150,16 +207,34 @@ declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
     content: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, string, string | Record<string, unknown>>;
     toolCallId: z.ZodString;
     name: z.ZodOptional<z.ZodString>;
+    cacheControl: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"ephemeral">;
+        ttl: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"5m">, z.ZodLiteral<"1h">]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }, {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     role: "tool";
     content: string;
     toolCallId: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }, {
     role: "tool";
     content: string | Record<string, unknown>;
     toolCallId: string;
     name?: string | undefined;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h" | undefined;
+    } | undefined;
 }>]>;
 export declare function safeParseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
 export declare function parseChatMessages(messages: (z.infer<typeof chatMessageSchema> & {

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

@@ -1,7 +1,7 @@
 import { AFS, type AFSExecOptions, type AFSExecResult, type AFSListOptions, type AFSListResult, type AFSModule, type AFSOptions, type AFSReadResult, type AFSSearchOptions } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import type * as prompts from "@inquirer/prompts";
-import { type ZodObject, type ZodType } from "zod";
+import { type ZodObject, type ZodType, z } 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";
@@ -9,7 +9,7 @@ import type { Memory, MemoryAgent } from "../memory/memory.js";
 import type { MemoryRecorderInput } from "../memory/recorder.js";
 import type { MemoryRetrieverInput } from "../memory/retriever.js";
 import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils.js";
-import type { ChatModel } from "./chat-model.js";
+import type { ChatModel, ChatModelInputMessage } from "./chat-model.js";
 import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import type { ImageModel } from "./image-model.js";
 import { type GetterSchema, type TransferAgentOutput } from "./types.js";
@@ -118,7 +118,6 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * agentSucceed, or agentFailed
      */
     disableEvents?: boolean;
-    historyConfig?: Agent["historyConfig"];
     /**
      * One or more memory agents this agent can use
      */
@@ -173,6 +172,10 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
      * This property only exists in the CLI context by command `aigne run`
      */
     prompts?: typeof prompts;
+    /**
+     * The caller agent that invoked this agent
+     */
+    caller?: Agent;
 }
 /**
  * Agent is the base class for all agents.
@@ -211,15 +214,15 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
         parsed: object;
     }): Promise<Agent<I, O>>;
     constructor(options?: AgentOptions<I, O>);
+    afs?: AFS;
+    tag?: string;
     /**
      * List of memories this agent can use
      *
      * @deprecated use afs instead
      */
     readonly memories: MemoryAgent[];
-    afs?: AFS;
     asyncMemoryRecord?: boolean;
-    tag?: string;
     /**
      * Maximum number of memory items to retrieve
      */
@@ -349,11 +352,6 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * agentSucceed, or agentFailed
      */
     private disableEvents?;
-    historyConfig?: {
-        disabled?: boolean;
-        maxTokens?: number;
-        maxItems?: number;
-    };
     private subscriptions;
     /**
      * Attach agent to context:
@@ -455,7 +453,9 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * @param options Invocation options
      * @returns Final processed output
      */
-    protected processAgentOutput(input: I, output: Exclude<AgentResponse<O>, AgentResponseStream<O>>, options: AgentInvokeOptions): Promise<O>;
+    protected processAgentOutput(input: I, output: Exclude<AgentResponse<O>, AgentResponseStream<O>>, { messages, ...options }: AgentInvokeOptions & {
+        messages?: ChatModelInputMessage[];
+    }): Promise<O>;
     /**
      * Process errors that occur during agent execution
      *
@@ -517,6 +517,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     protected postprocess(input: I, output: O, options: AgentInvokeOptions): Promise<void>;
     protected publishToTopics(output: Message, options: AgentInvokeOptions): Promise<void>;
+    formatOutput(output: O): PromiseOrValue<string>;
     /**
      * Core processing method of the agent, must be implemented in subclasses
      *
@@ -783,12 +784,31 @@ export interface AgentResponseProgress {
     } | {
         event: "agentFailed";
         error: Error;
+    } | {
+        event: "message";
+        message: ChatModelInputMessage;
     }) & Omit<AgentEvent, "agent"> & {
         agent: {
             name: string;
         };
     };
 }
+export type AgentResponseProgressMessageItem = {
+    type: "text";
+    content: string;
+} | {
+    type: "thinking";
+    thoughts: string;
+} | {
+    type: "tool_use";
+    toolUseId: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_result";
+    toolUseId: string;
+    content: unknown;
+};
 export declare function isAgentResponseProgress<T>(chunk: AgentResponseChunk<T>): chunk is AgentResponseProgress;
 /**
  * Creates a text delta for streaming responses
@@ -870,6 +890,17 @@ export interface FunctionAgentOptions<I extends Message = Message, O extends Mes
  */
 export declare class FunctionAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
     tag: string;
+    static schema(): ZodObject<{
+        process: ZodType<FunctionAgentFn>;
+    }, "strip", z.ZodTypeAny, {
+        process: FunctionAgentFn<any, any, FunctionAgent<any, any>>;
+    }, {
+        process: FunctionAgentFn<any, any, FunctionAgent<any, any>>;
+    }>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
     /**
      * Create a function agent from a function or options
      *

package/lib/esm/agents/agent.js

@@ -3,8 +3,10 @@ import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import equal from "fast-deep-equal";
 import nunjucks from "nunjucks";
 import { joinURL } from "ufo";
+import { stringify } from "yaml";
 import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
+import { codeToFunctionAgentFn } from "../loader/function-agent.js";
 import { sortHooks } from "../utils/agent-utils.js";
 import { getZodObjectKeys, isZodSchema } from "../utils/json-schema.js";
 import { logger } from "../utils/logger.js";
@@ -103,7 +105,6 @@ export class Agent {
         if (options.skills?.length)
             this.skills.push(...options.skills.map(functionToAgent));
         this.disableEvents = options.disableEvents;
-        this.historyConfig = options.historyConfig;
         if (Array.isArray(options.memory)) {
             this.memories.push(...options.memory);
         }
@@ -130,15 +131,15 @@ export class Agent {
                     : options.retryOnError;
         this.guideRails = options.guideRails;
     }
+    afs;
+    tag;
     /**
      * List of memories this agent can use
      *
      * @deprecated use afs instead
      */
     memories = [];
-    afs;
     asyncMemoryRecord;
-    tag;
     /**
      * Maximum number of memory items to retrieve
      */
@@ -283,7 +284,6 @@ export class Agent {
      * agentSucceed, or agentFailed
      */
     disableEvents;
-    historyConfig;
     subscriptions = [];
     /**
      * Attach agent to context:
@@ -414,11 +414,15 @@ export class Agent {
                     : isAsyncGenerator(response)
                         ? asyncGeneratorToReadableStream(response)
                         : objectToAgentResponseStream(response);
+                const messages = [];
                 for await (const chunk of stream) {
                     mergeAgentResponseChunk(output, chunk);
                     yield chunk;
+                    if (isAgentResponseProgress(chunk) && chunk.progress.event === "message") {
+                        messages.push(chunk.progress.message);
+                    }
                 }
-                let result = await this.processAgentOutput(input, output, options);
+                let result = await this.processAgentOutput(input, output, { ...options, messages });
                 if (attempt > 0) {
                     result = { ...result, $meta: { ...result.$meta, retries: attempt } };
                 }
@@ -503,6 +507,7 @@ export class Agent {
             ...options,
             model: this.model || options.model,
             imageModel: this.imageModel || options.imageModel,
+            caller: this,
         });
     });
     /**
@@ -515,7 +520,7 @@ export class Agent {
      * @param options Invocation options
      * @returns Final processed output
      */
-    async processAgentOutput(input, output, options) {
+    async processAgentOutput(input, output, { messages, ...options }) {
         const { context } = options;
         if (!isRecord(output)) {
             throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof output}): ${output}`);
@@ -527,8 +532,14 @@ export class Agent {
         const o = await this.callHooks(["onSuccess", "onEnd"], { input, output: finalOutput }, options);
         if (o?.output)
             finalOutput = o.output;
-        if (this.historyConfig?.disabled !== true)
-            this.afs?.emit("agentSucceed", { input, output: finalOutput });
+        this.afs?.emit("agentSucceed", {
+            agentId: this.name,
+            userId: context.userContext.userId,
+            sessionId: context.userContext.sessionId,
+            input,
+            output: finalOutput,
+            messages,
+        });
         if (!this.disableEvents)
             context.emit("agentSucceed", { agent: this, output: finalOutput });
         return finalOutput;
@@ -658,6 +669,9 @@ export class Agent {
             });
         }
     }
+    formatOutput(output) {
+        return stringify(output);
+    }
     /**
      * Shut down the agent and clean up resources
      *
@@ -824,6 +838,18 @@ function checkAgentInputOutputSchema(schema) {
  */
 export class FunctionAgent extends Agent {
     tag = "FunctionAgent";
+    static schema() {
+        return z.object({
+            process: z.preprocess((v) => (typeof v === "string" ? codeToFunctionAgentFn(v) : v), z.custom()),
+        });
+    }
+    static async load(options) {
+        const valid = await FunctionAgent.schema().parseAsync(options.parsed);
+        return new FunctionAgent({
+            ...options.parsed,
+            process: valid.process,
+        });
+    }
     /**
      * Create a function agent from a function or options
      *

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

@@ -1,4 +1,8 @@
 import { type ZodObject, type ZodType, z } from "zod";
+import { type NestAgentSchema } from "../loader/agent-yaml.js";
+import type { AgentLoadOptions } from "../loader/index.js";
+import { type Instructions } from "../loader/schema.js";
+import type { CompactConfig, SessionMemoryConfig, UserMemoryConfig } from "../prompt/agent-session.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type AgentProcessResult, type Message } from "./agent.js";
 import type { ChatModel, ChatModelInput } from "./chat-model.js";
@@ -23,8 +27,6 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * more complex prompt templates
      */
     instructions?: string | PromptBuilder;
-    autoReorderSystemMessages?: boolean;
-    autoMergeSystemMessages?: boolean;
     /**
      * Pick a message from input to use as the user's message
      */
@@ -124,6 +126,53 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      */
     memoryPromptTemplate?: string;
     useMemoriesFromContext?: boolean;
+    /**
+     * Agent session configuration
+     *
+     * Controls history recording, memory extraction, and conversation compaction.
+     * By default, mode is "auto" (enabled). Set `{ mode: "disabled" }` to disable
+     * for internal utility agents (extractors, compactors, etc.).
+     *
+     * @example
+     * ```typescript
+     * // Default behavior - session features enabled
+     * new AIAgent({
+     *   session: {
+     *     compact: { mode: "auto" },
+     *     sessionMemory: { mode: "auto" },
+     *     userMemory: { mode: "auto" }
+     *   }
+     * })
+     *
+     * // Disable for internal utility agents
+     * new AIAgent({
+     *   session: { mode: "disabled" }
+     * })
+     * ```
+     */
+    session?: Partial<Omit<import("../prompt/agent-session.js").AgentSessionOptions, "sessionId" | "userId" | "agentId" | "afs">>;
+}
+export interface AIAgentLoadSchema {
+    instructions?: Instructions;
+    inputKey?: string;
+    inputFileKey?: string;
+    outputKey?: string;
+    outputFileKey?: string;
+    toolChoice?: AIAgentToolChoice;
+    toolCallsConcurrency?: number;
+    keepTextInToolUses?: boolean;
+    session?: {
+        mode?: "auto" | "disabled";
+        compact?: Omit<CompactConfig, "compactor"> & {
+            compactor?: NestAgentSchema;
+        };
+        sessionMemory?: Omit<SessionMemoryConfig, "extractor"> & {
+            extractor?: NestAgentSchema;
+        };
+        userMemory?: Omit<UserMemoryConfig, "extractor"> & {
+            extractor?: NestAgentSchema;
+        };
+    };
 }
 /**
  * Tool choice options for AI agents
@@ -188,6 +237,14 @@ export declare const aiAgentOptionsSchema: ZodObject<{
  */
 export declare class AIAgent<I extends Message = any, O extends Message = any> extends Agent<I, O> {
     tag: string;
+    static schema<T>({ filepath }: {
+        filepath: string;
+    }): ZodType<T>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+        options?: AgentLoadOptions;
+    }): Promise<Agent<I, O>>;
     /**
      * Create an AIAgent with the specified options
      *
@@ -218,8 +275,6 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-prompt-builder}
      */
     instructions: PromptBuilder;
-    autoReorderSystemMessages?: boolean;
-    autoMergeSystemMessages?: boolean;
     /**
      * Pick a message from input to use as the user's message
      */
@@ -315,6 +370,10 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
         metadataEnd: string;
         parse: (raw: string) => object;
     };
+    /**
+     * Agent session configuration
+     */
+    session?: Partial<Omit<import("../prompt/agent-session.js").AgentSessionOptions, "sessionId" | "userId" | "agentId" | "afs">>;
     get inputSchema(): ZodType<I>;
     /**
      * Process an input message and generate a response