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

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

@@ -203,6 +203,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 +225,64 @@ export type ChatModelInputMessageContent = string | UnionContent[];
 export type TextContent = {
     type: "text";
     text: string;
+    /**
+     * 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 +384,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 +414,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 +523,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 +629,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 +648,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

@@ -188,6 +188,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;
         }
@@ -244,6 +248,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 +273,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 +298,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 +309,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(),
@@ -341,6 +373,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({

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

@@ -1,4 +1,4 @@
-import { type ZodObject, type ZodType } from "zod";
+import z, { type ZodObject, type ZodType } from "zod";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type Message } from "./agent.js";
 import { type ImageModelOutput } from "./image-model.js";
@@ -13,6 +13,22 @@ export declare const imageAgentOptionsSchema: ZodObject<{
 }>;
 export declare class ImageAgent<I extends Message = any, O extends ImageModelOutput = any> extends Agent<I, O> {
     tag: string;
+    static schema({ filepath }: {
+        filepath: string;
+    }): z.ZodObject<{
+        instructions: z.ZodType<import("../loader/schema.js").Instructions, z.ZodTypeDef, import("../loader/schema.js").Instructions>;
+        inputFileKey: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+    }, "strip", z.ZodTypeAny, {
+        instructions: import("../loader/schema.js").Instructions;
+        inputFileKey?: string | undefined;
+    }, {
+        instructions: import("../loader/schema.js").Instructions;
+        inputFileKey?: string | undefined;
+    }>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
     static from<I extends Message = any, O extends ImageModelOutput = any>(options: ImageAgentOptions<I, O>): ImageAgent<I, O>;
     constructor(options: ImageAgentOptions<I, O>);
     instructions: PromptBuilder;

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

@@ -1,4 +1,5 @@
 import z from "zod";
+import { camelizeSchema, getInstructionsSchema, instructionsToPromptBuilder, optionalize, } from "../loader/schema.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { checkArguments } from "../utils/type-utils.js";
 import { Agent, agentOptionsSchema, } from "./agent.js";
@@ -10,6 +11,21 @@ export const imageAgentOptionsSchema = agentOptionsSchema.extend({
 });
 export class ImageAgent extends Agent {
     tag = "ImageAgent";
+    static schema({ filepath }) {
+        const instructionsSchema = getInstructionsSchema({ filepath });
+        return camelizeSchema(z.object({
+            instructions: instructionsSchema,
+            inputFileKey: optionalize(z.string()),
+        }));
+    }
+    static async load(options) {
+        const valid = await ImageAgent.schema({ filepath: options.filepath }).parseAsync(options.parsed);
+        return new ImageAgent({
+            ...options.parsed,
+            ...valid,
+            instructions: instructionsToPromptBuilder(valid.instructions),
+        });
+    }
     static from(options) {
         return new ImageAgent(options);
     }

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

@@ -91,6 +91,7 @@ export declare const imageModelInputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     modelOptions?: Record<string, unknown> | undefined;
+    outputFileType?: "local" | "url" | "file" | undefined;
     image?: ({
         type: "url";
         url: string;
@@ -107,11 +108,11 @@ export declare const imageModelInputSchema: z.ZodObject<{
         filename?: string | undefined;
         mimeType?: string | undefined;
     })[] | undefined;
-    outputFileType?: "local" | "file" | "url" | undefined;
     n?: number | undefined;
 }, {
     prompt: string;
     modelOptions?: Record<string, unknown> | undefined;
+    outputFileType?: "local" | "url" | "file" | undefined;
     image?: ({
         type: "url";
         url: string;
@@ -128,7 +129,6 @@ export declare const imageModelInputSchema: z.ZodObject<{
         filename?: string | undefined;
         mimeType?: string | undefined;
     })[] | undefined;
-    outputFileType?: "local" | "file" | "url" | undefined;
     n?: number | undefined;
 }>;
 export interface ImageModelOutput extends Message {
@@ -196,16 +196,22 @@ export declare const imageModelOutputSchema: 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;
     }>>;
     model: z.ZodOptional<z.ZodString>;
@@ -226,13 +232,15 @@ export declare const imageModelOutputSchema: z.ZodObject<{
         filename?: string | undefined;
         mimeType?: string | undefined;
     })[];
-    model?: string | undefined;
     usage?: {
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     } | undefined;
+    model?: string | undefined;
 }, {
     images: ({
         type: "url";
@@ -250,11 +258,13 @@ export declare const imageModelOutputSchema: z.ZodObject<{
         filename?: string | undefined;
         mimeType?: string | undefined;
     })[];
-    model?: string | undefined;
     usage?: {
         inputTokens: number;
         outputTokens: number;
         aigneHubCredits?: number | undefined;
+        cacheCreationInputTokens?: number | undefined;
+        cacheReadInputTokens?: number | undefined;
         creditPrefix?: "$" | "€" | "¥" | undefined;
     } | undefined;
+    model?: string | undefined;
 }>;

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

@@ -58,6 +58,23 @@ export type SSEServerParameters = {
  */
 export declare class MCPAgent extends Agent {
     tag: string;
+    static schema(): z.ZodObject<{
+        url: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        command: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        args: ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    }, "strip", z.ZodTypeAny, {
+        url?: string | undefined;
+        args?: string[] | undefined;
+        command?: string | undefined;
+    }, {
+        url?: string | undefined;
+        args?: string[] | undefined;
+        command?: string | undefined;
+    }>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
     /**
      * Create an MCPAgent from a connection to an SSE server.
      *

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

@@ -5,6 +5,7 @@ import { SSEClientTransport, } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport, } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { UriTemplate } from "@modelcontextprotocol/sdk/shared/uriTemplate.js";
 import { z } from "zod";
+import { optionalize } from "../loader/schema.js";
 import { logger } from "../utils/logger.js";
 import { promptFromMCPPrompt, resourceFromMCPResource, toolFromMCPTool, } from "../utils/mcp-utils.js";
 import { checkArguments, createAccessorArray } from "../utils/type-utils.js";
@@ -49,6 +50,23 @@ function getMCPServerString(options) {
  */
 export class MCPAgent extends Agent {
     tag = "MCPAgent";
+    static schema() {
+        return z.object({
+            url: optionalize(z.string()),
+            command: optionalize(z.string()),
+            args: optionalize(z.array(z.string())),
+        });
+    }
+    static async load(options) {
+        const valid = await MCPAgent.schema().parseAsync(options.parsed);
+        if (!valid.url && !valid.command) {
+            throw new Error(`Missing url or command in mcp agent: ${options.filepath}`);
+        }
+        return MCPAgent.from({
+            ...options.parsed,
+            ...valid,
+        });
+    }
     static from(options) {
         checkArguments("MCPAgent.from", mcpAgentOptionsSchema, options);
         if (isSSEServerParameters(options)) {

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

@@ -1,3 +1,5 @@
+import { z } from "zod";
+import type { AgentLoadOptions } from "../loader/index.js";
 import { type PromiseOrValue } from "../utils/type-utils.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type Message } from "./agent.js";
 /**
@@ -200,6 +202,59 @@ export interface TeamAgentOptions<I extends Message, O extends Message> extends
  */
 export declare class TeamAgent<I extends Message, O extends Message> extends Agent<I, O> {
     tag: string;
+    static schema({ filepath }: {
+        filepath: string;
+    }): z.ZodObject<{
+        mode: z.ZodType<ProcessMode | undefined, z.ZodTypeDef, ProcessMode | undefined>;
+        iterateOn: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        concurrency: z.ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+        iterateWithPreviousOutput: z.ZodType<boolean | undefined, z.ZodTypeDef, boolean | undefined>;
+        includeAllStepsOutput: z.ZodType<boolean | undefined, z.ZodTypeDef, boolean | undefined>;
+        reflection: z.ZodType<{
+            reviewer: import("../loader/agent-yaml.js").NestAgentSchema;
+            isApproved: string;
+            maxIterations?: number | undefined;
+            returnLastOnMaxIterations?: boolean | undefined;
+            customErrorMessage?: string | undefined;
+        } | undefined, z.ZodTypeDef, {
+            reviewer: import("../loader/agent-yaml.js").NestAgentSchema;
+            isApproved: string;
+            maxIterations?: number | undefined;
+            returnLastOnMaxIterations?: boolean | undefined;
+            customErrorMessage?: string | undefined;
+        } | undefined>;
+    }, "strip", z.ZodTypeAny, {
+        mode?: ProcessMode | undefined;
+        reflection?: {
+            reviewer: import("../loader/agent-yaml.js").NestAgentSchema;
+            isApproved: string;
+            maxIterations?: number | undefined;
+            returnLastOnMaxIterations?: boolean | undefined;
+            customErrorMessage?: string | undefined;
+        } | undefined;
+        iterateOn?: string | undefined;
+        concurrency?: number | undefined;
+        iterateWithPreviousOutput?: boolean | undefined;
+        includeAllStepsOutput?: boolean | undefined;
+    }, {
+        mode?: ProcessMode | undefined;
+        reflection?: {
+            reviewer: import("../loader/agent-yaml.js").NestAgentSchema;
+            isApproved: string;
+            maxIterations?: number | undefined;
+            returnLastOnMaxIterations?: boolean | undefined;
+            customErrorMessage?: string | undefined;
+        } | undefined;
+        iterateOn?: string | undefined;
+        concurrency?: number | undefined;
+        iterateWithPreviousOutput?: boolean | undefined;
+        includeAllStepsOutput?: boolean | undefined;
+    }>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+        options: AgentLoadOptions;
+    }): Promise<Agent<I, O>>;
     /**
      * Create a TeamAgent from the provided options.
      *

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

@@ -1,5 +1,8 @@
 import assert from "node:assert";
 import { produce } from "immer";
+import { z } from "zod";
+import { getNestAgentSchema } from "../loader/agent-yaml.js";
+import { camelizeSchema, optionalize } from "../loader/schema.js";
 import * as fastq from "../utils/queue.js";
 import { mergeAgentResponseChunk } from "../utils/stream-utils.js";
 import { isEmpty, isNil, isRecord, omit } from "../utils/type-utils.js";
@@ -47,6 +50,34 @@ export const DEFAULT_REFLECTION_MAX_ITERATIONS = 3;
  */
 export class TeamAgent extends Agent {
     tag = "TeamAgent";
+    static schema({ filepath }) {
+        const nestAgentSchema = getNestAgentSchema({ filepath });
+        return z.object({
+            mode: optionalize(z.nativeEnum(ProcessMode)),
+            iterateOn: optionalize(z.string()),
+            concurrency: optionalize(z.number().int().min(1)),
+            iterateWithPreviousOutput: optionalize(z.boolean()),
+            includeAllStepsOutput: optionalize(z.boolean()),
+            reflection: camelizeSchema(optionalize(z.object({
+                reviewer: nestAgentSchema,
+                isApproved: z.string(),
+                maxIterations: optionalize(z.number().int().min(1)),
+                returnLastOnMaxIterations: optionalize(z.boolean()),
+                customErrorMessage: optionalize(z.string()),
+            }))),
+        });
+    }
+    static async load(options) {
+        const valid = await TeamAgent.schema({ filepath: options.filepath }).parseAsync(options.parsed);
+        return TeamAgent.from({
+            ...options.parsed,
+            ...valid,
+            reflection: valid.reflection && {
+                ...valid.reflection,
+                reviewer: await options.options.loadNestAgent(options.filepath, valid.reflection.reviewer, options.options),
+            },
+        });
+    }
     /**
      * Create a TeamAgent from the provided options.
      *

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

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { Agent, type AgentOptions, type Message } from "./agent.js";
 /**
  * Configuration options for TransformAgent
@@ -47,6 +48,17 @@ export interface TransformAgentOptions<I extends Message, O extends Message> ext
  */
 export declare class TransformAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
     static type: string;
+    static schema(): z.ZodObject<{
+        jsonata: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        jsonata: string;
+    }, {
+        jsonata: string;
+    }>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
     /**
      * Factory method to create a new TransformAgent instance
      *

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

@@ -1,4 +1,5 @@
 import jsonata from "jsonata";
+import { z } from "zod";
 import { Agent } from "./agent.js";
 /**
  * TransformAgent - A specialized agent for data transformation using JSONata expressions
@@ -17,6 +18,18 @@ import { Agent } from "./agent.js";
  */
 export class TransformAgent extends Agent {
     static type = "TransformAgent";
+    static schema() {
+        return z.object({
+            jsonata: z.string(),
+        });
+    }
+    static async load(options) {
+        const parsed = await TransformAgent.schema().parseAsync(options.parsed);
+        return TransformAgent.from({
+            ...options.parsed,
+            ...parsed,
+        });
+    }
     /**
      * Factory method to create a new TransformAgent instance
      *