@node-llm/core 1.11.0 → 1.12.0

package/dist/agent/Agent.d.ts

@@ -7,17 +7,21 @@ import { ThinkingConfig, ThinkingResult } from "../providers/Provider.js";
 import { Schema } from "../schema/Schema.js";
 import { NodeLLMCore } from "../llm.js";
 /**
- * Configuration options that can be defined as static properties on Agent subclasses.
+ * A value that can be a static T or a function that returns T based on inputs.
  */
-export interface AgentConfig {
-    /** The model ID to use (e.g., "gpt-4o", "claude-sonnet-4-20250514") */
+export type LazyValue<T, I = any> = T | ((inputs: I) => T);
+/**
+ * Configuration options for Agent.
+ */
+export interface AgentConfig<I = any> {
+    /** The model ID to use (e.g., "gpt-4o") */
     model?: string;
-    /** The provider to use (e.g., "openai", "anthropic") */
+    /** The provider to use (e.g., "openai") */
     provider?: string;
-    /** System instructions for the agent */
-    instructions?: string;
-    /** Tools available to the agent */
-    tools?: ToolResolvable[];
+    /** System instructions for the agent (can be lazy) */
+    instructions?: LazyValue<string, I>;
+    /** Tools available to the agent (can be lazy) */
+    tools?: LazyValue<ToolResolvable[], I>;
     /** Temperature for response generation (0.0 - 1.0) */
     temperature?: number;
     /** Extended thinking configuration */
@@ -36,36 +40,17 @@ export interface AgentConfig {
     assumeModelExists?: boolean;
     /** Optional LLM instance to use instead of global NodeLLM */
     llm?: NodeLLMCore;
+    /** Optional initial inputs to resolve lazy config immediately */
+    inputs?: I;
 }
 /**
  * Base class for creating reusable, class-configured agents.
- *
- * Define your agent configuration using static properties, then instantiate
- * and use it anywhere in your application.
- *
- * @example
- * ```typescript
- * class SupportAgent extends Agent {
- *   static model = "gpt-4o";
- *   static instructions = "You are a helpful support agent";
- *   static tools = [SearchDocs, LookupAccount];
- *   static temperature = 0.2;
- * }
- *
- * const agent = new SupportAgent();
- * const response = await agent.ask("How can I reset my password?");
- * ```
- *
- * @example Override configuration per instance:
- * ```typescript
- * const agent = new SupportAgent({ model: "gpt-4o-mini" });
- * ```
  */
-export declare abstract class Agent<S extends Record<string, unknown> = Record<string, unknown>> {
+export declare abstract class Agent<I extends Record<string, any> = Record<string, any>, S extends Record<string, unknown> = Record<string, unknown>> {
     static model?: string;
     static provider?: string;
-    static instructions?: string;
-    static tools?: ToolResolvable[];
+    static instructions?: LazyValue<string, any>;
+    static tools?: LazyValue<ToolResolvable[], any>;
     static temperature?: number;
     static thinking?: ThinkingConfig;
     static schema?: z.ZodType | Schema | Record<string, unknown>;
@@ -74,86 +59,101 @@ export declare abstract class Agent<S extends Record<string, unknown> = Record<s
     static maxTokens?: number;
     static maxToolCalls?: number;
     static assumeModelExists?: boolean;
+    /**
+     * Explicitly declare which inputs this agent expects.
+     * Useful for introspection and validation.
+     */
+    static inputs?: string[];
     /**
      * Hook called when the agent starts a new session (ask/stream).
-     * @param context - Initial context including messages/options
      */
     static onStart(_context: {
         messages: unknown[];
     }): void | Promise<void>;
-    /**
-     * Hook called when the agent generates a reasoning trace (thinking).
-     * @param thinking - The content of the thinking trace
-     * @param result - The full response object containing the thinking
-     */
     static onThinking(_thinking: ThinkingResult, _result: ChatResponseString): void | Promise<void>;
-    /**
-     * Hook called when a tool execution starts.
-     * @param toolCall - The tool call object (id, function name, arguments)
-     */
     static onToolStart(_toolCall: unknown): void | Promise<void>;
-    /**
-     * Hook called when a tool execution ends.
-     * @param toolCall - The tool call object
-     * @param result - The result of the tool execution
-     */
     static onToolEnd(_toolCall: unknown, _result: unknown): void | Promise<void>;
-    /**
-     * Hook called when a tool execution encounters an error.
-     * @param toolCall - The tool call object
-     * @param error - The error that occurred
-     */
     static onToolError(_toolCall: unknown, _error: Error): void | Promise<void>;
-    /**
-     * Hook called when the agent completes a response turn.
-     * @param result - The final response object
-     */
     static onComplete(_result: ChatResponseString): void | Promise<void>;
     /**
      * Run the agent immediately with a prompt.
-     * Creates a new instance of the agent, runs the prompt, and disposes it.
-     *
-     * @example
-     * ```typescript
-     * const result = await TravelAgent.ask("Find flights to Paris");
-     * ```
      */
-    static ask(message: string, options?: AskOptions): Promise<ChatResponseString>;
+    static ask<I extends Record<string, any>, S extends Record<string, any>>(this: new (overrides?: Partial<AgentConfig<I> & ChatOptions>) => Agent<I, S>, message: string, options?: AskOptions & {
+        inputs?: I;
+    }): Promise<ChatResponseString>;
     /**
      * Stream the agent response immediately.
-     * Creates a new instance of the agent and streams the response.
-     *
-     * @example
-     * ```typescript
-     * for await (const chunk of TravelAgent.stream("Write a poem")) {
-     *   process.stdout.write(chunk.content);
-     * }
-     * ```
-     */
-    static stream(message: string, options?: AskOptions): import("../index.js").Stream<import("../providers/Provider.js").ChatChunk>;
+     */
+    static stream<I extends Record<string, any>, S extends Record<string, any>>(this: new (overrides?: Partial<AgentConfig<I> & ChatOptions>) => Agent<I, S>, message: string, options?: AskOptions & {
+        inputs?: I;
+    }): import("../index.js").Stream<import("../providers/Provider.js").ChatChunk>;
     /** The underlying Chat instance */
     protected readonly chat: Chat<S>;
+    /** Private reference to configuration overrides for lazy resolution */
+    private readonly config;
     /**
      * Create a new agent instance.
      * @param overrides - Optional configuration to override static properties
      */
-    constructor(overrides?: Partial<AgentConfig & ChatOptions>);
+    constructor(overrides?: Partial<AgentConfig<I> & ChatOptions>);
+    /**
+     * Helper to resolve lazy instructions and tools based on inputs.
+     */
+    private resolveLazyConfig;
+    /**
+     * Add instructions to the agent (replaces or appends).
+     */
+    withInstructions(instructions: string, options?: {
+        replace?: boolean;
+    }): this;
+    /**
+     * Add tools to the agent.
+     */
+    withTools(tools: ToolResolvable[], options?: {
+        replace?: boolean;
+    }): this;
+    /**
+     * Alias for withTools([tool]).
+     */
+    use(tool: ToolResolvable): this;
     /**
      * Send a message to the agent and get a response.
-     * @param message - The user message
-     * @param options - Optional request options
      */
-    ask(message: string, options?: AskOptions): Promise<ChatResponseString>;
+    ask(message: string, options?: AskOptions & {
+        inputs?: I;
+    }): Promise<ChatResponseString>;
+    /**
+     * Hook called when a tool call starts.
+     */
+    onToolCallStart(handler: (toolCall: any) => void | Promise<void>): this;
+    /**
+     * Hook called when a tool call ends.
+     */
+    onToolCallEnd(handler: (toolCall: any, result: any) => void | Promise<void>): this;
+    /**
+     * Hook called when a tool call errors.
+     */
+    onToolCallError(handler: (toolCall: any, error: Error) => any): this;
+    /**
+     * Hook called before a request.
+     */
+    beforeRequest(handler: (messages: any[]) => any): this;
+    /**
+     * Hook called after a response.
+     */
+    afterResponse(handler: (response: ChatResponseString) => any): this;
     /**
      * Alias for ask()
      */
-    say(message: string, options?: AskOptions): Promise<ChatResponseString>;
+    say(message: string, options?: AskOptions & {
+        inputs?: I;
+    }): Promise<ChatResponseString>;
     /**
      * Stream a response from the agent.
-     * @param message - The user message
-     * @param options - Optional request options
      */
-    stream(message: string, options?: AskOptions): import("../index.js").Stream<import("../providers/Provider.js").ChatChunk>;
+    stream(message: string, options?: AskOptions & {
+        inputs?: I;
+    }): import("../index.js").Stream<import("../providers/Provider.js").ChatChunk>;
     /**
      * Get the conversation history.
      */
@@ -173,19 +173,6 @@ export declare abstract class Agent<S extends Record<string, unknown> = Record<s
 }
 /**
  * Helper function to define an agent inline without creating a class.
- *
- * @example
- * ```typescript
- * const SupportAgent = defineAgent({
- *   model: "gpt-4o",
- *   instructions: "You are a helpful support agent",
- *   tools: [SearchDocs, LookupAccount],
- *   temperature: 0.2
- * });
- *
- * const agent = new SupportAgent();
- * const response = await agent.ask("Help me!");
- * ```
  */
-export declare function defineAgent<S extends Record<string, unknown> = Record<string, unknown>>(config: AgentConfig): new (overrides?: Partial<AgentConfig & ChatOptions>) => Agent<S>;
+export declare function defineAgent<I extends Record<string, any> = Record<string, any>, S extends Record<string, unknown> = Record<string, unknown>>(config: AgentConfig<I>): new (overrides?: Partial<AgentConfig<I> & ChatOptions>) => Agent<I, S>;
 //# sourceMappingURL=Agent.d.ts.map

package/dist/agent/Agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAW,WAAW,EAAE,MAAM,WAAW,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,GAAG;IAClC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,sDAAsD;IACtD,YAAY,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAEpC,iDAAiD;IACjD,KAAK,CAAC,EAAE,SAAS,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC;IAEvC,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAE1B,6CAA6C;IAC7C,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtD,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B,6DAA6D;IAC7D,GAAG,CAAC,EAAE,WAAW,CAAC;IAElB,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,CAAC;CACZ;AAED;;GAEG;AACH,8BAAsB,KAAK,CACzB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACnD,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAG3D,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7C,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,cAAc,EAAE,EAAE,GAAG,CAAC,CAAC;IAChD,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC5B,MAAM,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACjC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7D,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE;QAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvE,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/F,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,MAAM,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3E,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpE;;OAEG;WACU,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3E,IAAI,EAAE,KAAK,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5E,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GACpC,OAAO,CAAC,kBAAkB,CAAC;IAK9B;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxE,IAAI,EAAE,KAAK,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5E,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,UAAU,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE;IAMvC,mCAAmC;IACnC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAEjC,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAE/D;;;OAGG;gBACS,SAAS,GAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAM;IAuFjE;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA0BzB;;OAEG;IACH,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAK7E;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAKzE;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAI/B;;OAEG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAO9F;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAKvE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAKlF;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,KAAK,GAAG,GAAG,IAAI;IAKpE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,GAAG,GAAG,IAAI;IAKtD;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,kBAAkB,KAAK,GAAG,GAAG,IAAI;IAKnE;;OAEG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI9F;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE;IAO7D;;OAEG;IACH,IAAI,OAAO,6CAEV;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;OAEG;IACH,IAAI,UAAU,6CAEb;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,IAAI,CAAC,CAAC,CAAC,CAE5B;CACF;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACnD,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAehG"}

package/dist/agent/Agent.js

@@ -1,27 +1,6 @@
 import { NodeLLM } from "../llm.js";
 /**
  * Base class for creating reusable, class-configured agents.
- *
- * Define your agent configuration using static properties, then instantiate
- * and use it anywhere in your application.
- *
- * @example
- * ```typescript
- * class SupportAgent extends Agent {
- *   static model = "gpt-4o";
- *   static instructions = "You are a helpful support agent";
- *   static tools = [SearchDocs, LookupAccount];
- *   static temperature = 0.2;
- * }
- *
- * const agent = new SupportAgent();
- * const response = await agent.ask("How can I reset my password?");
- * ```
- *
- * @example Override configuration per instance:
- * ```typescript
- * const agent = new SupportAgent({ model: "gpt-4o-mini" });
- * ```
  */
 export class Agent {
     // Static configuration properties - override these in subclasses
@@ -37,89 +16,57 @@ export class Agent {
     static maxTokens;
     static maxToolCalls;
     static assumeModelExists;
+    /**
+     * Explicitly declare which inputs this agent expects.
+     * Useful for introspection and validation.
+     */
+    static inputs;
     /**
      * Hook called when the agent starts a new session (ask/stream).
-     * @param context - Initial context including messages/options
      */
     static onStart(_context) {
         // Override in subclass
     }
-    /**
-     * Hook called when the agent generates a reasoning trace (thinking).
-     * @param thinking - The content of the thinking trace
-     * @param result - The full response object containing the thinking
-     */
     static onThinking(_thinking, _result) {
         // Override in subclass
     }
-    /**
-     * Hook called when a tool execution starts.
-     * @param toolCall - The tool call object (id, function name, arguments)
-     */
     static onToolStart(_toolCall) {
         // Override in subclass
     }
-    /**
-     * Hook called when a tool execution ends.
-     * @param toolCall - The tool call object
-     * @param result - The result of the tool execution
-     */
     static onToolEnd(_toolCall, _result) {
         // Override in subclass
     }
-    /**
-     * Hook called when a tool execution encounters an error.
-     * @param toolCall - The tool call object
-     * @param error - The error that occurred
-     */
     static onToolError(_toolCall, _error) {
         // Override in subclass
     }
-    /**
-     * Hook called when the agent completes a response turn.
-     * @param result - The final response object
-     */
     static onComplete(_result) {
         // Override in subclass
     }
     // --- Static Execution API ---
     /**
      * Run the agent immediately with a prompt.
-     * Creates a new instance of the agent, runs the prompt, and disposes it.
-     *
-     * @example
-     * ```typescript
-     * const result = await TravelAgent.ask("Find flights to Paris");
-     * ```
      */
     static async ask(message, options) {
-        const Ctor = this;
-        const agent = new Ctor({});
+        const agent = new this({ ...options });
         return agent.ask(message, options);
     }
     /**
      * Stream the agent response immediately.
-     * Creates a new instance of the agent and streams the response.
-     *
-     * @example
-     * ```typescript
-     * for await (const chunk of TravelAgent.stream("Write a poem")) {
-     *   process.stdout.write(chunk.content);
-     * }
-     * ```
      */
     static stream(message, options) {
-        const Ctor = this;
-        const agent = new Ctor({});
+        const agent = new this({ ...options });
         return agent.stream(message, options);
     }
     /** The underlying Chat instance */
     chat;
+    /** Private reference to configuration overrides for lazy resolution */
+    config;
     /**
      * Create a new agent instance.
      * @param overrides - Optional configuration to override static properties
      */
     constructor(overrides = {}) {
+        this.config = overrides;
         const ctor = this.constructor;
         // Build chat options from static properties + overrides
         const chatOptions = {
@@ -131,53 +78,58 @@ export class Agent {
             headers: { ...ctor.headers, ...overrides.headers },
             params: { ...ctor.params, ...overrides.params },
             thinking: overrides.thinking ?? ctor.thinking,
-            messages: overrides.messages // Allow history injection
+            messages: overrides.messages
         };
         // Determine model
         const model = overrides.model ?? ctor.model;
         if (!model) {
             throw new Error(`[Agent] No model specified. Set static model property or pass model in constructor.`);
         }
-        // Use provided LLM instance or fall back to global NodeLLM
         const llm = overrides.llm ?? NodeLLM;
         this.chat = llm.chat(model, chatOptions);
-        // Apply instructions
-        const instructions = overrides.instructions ?? ctor.instructions;
-        if (instructions) {
-            this.chat.withInstructions(instructions);
+        // Initial resolution if inputs are provided in constructor
+        if (overrides.inputs) {
+            this.resolveLazyConfig(overrides.inputs);
         }
-        // Apply tools
-        const tools = overrides.tools ?? ctor.tools;
-        if (tools && tools.length > 0) {
-            this.chat.withTools(tools);
+        else {
+            // Fallback: apply static/direct instructions immediately if they aren't functions
+            const instructions = overrides.instructions ?? ctor.instructions;
+            if (instructions && typeof instructions !== "function") {
+                this.chat.withInstructions(instructions);
+            }
+            const tools = overrides.tools ?? ctor.tools;
+            if (tools && typeof tools !== "function" && tools.length > 0) {
+                this.chat.withTools(tools);
+            }
         }
         // Apply schema
         const schema = overrides.schema ?? ctor.schema;
         if (schema) {
             this.chat.withSchema(schema);
         }
-        // Wire up global/static telemetry hooks
-        // Trigger onStart immediately
+        // Wire up telemetry hooks
         if (ctor.onStart) {
             this.chat.beforeRequest(async (messages) => {
-                if (ctor.onStart) {
+                if (ctor.onStart)
                     await ctor.onStart({ messages });
-                }
             });
         }
         if (ctor.onToolStart) {
             this.chat.onToolCallStart(async (toolCall) => {
-                await ctor.onToolStart(toolCall);
+                if (ctor.onToolStart)
+                    await ctor.onToolStart(toolCall);
             });
         }
         if (ctor.onToolEnd) {
             this.chat.onToolCallEnd(async (toolCall, result) => {
-                await ctor.onToolEnd(toolCall, result);
+                if (ctor.onToolEnd)
+                    await ctor.onToolEnd(toolCall, result);
             });
         }
         if (ctor.onToolError) {
             this.chat.onToolCallError(async (toolCall, error) => {
-                await ctor.onToolError(toolCall, error);
+                if (ctor.onToolError)
+                    await ctor.onToolError(toolCall, error);
             });
         }
         if (ctor.onComplete || ctor.onThinking) {
@@ -191,14 +143,95 @@ export class Agent {
             });
         }
     }
+    /**
+     * Helper to resolve lazy instructions and tools based on inputs.
+     */
+    resolveLazyConfig(inputs) {
+        if (!inputs)
+            return;
+        const ctor = this.constructor;
+        // 1. Resolve Instructions
+        let instructions = this.config.instructions ?? ctor.instructions;
+        if (typeof instructions === "function") {
+            instructions = instructions(inputs);
+        }
+        if (typeof instructions === "string") {
+            this.chat.withInstructions(instructions, { replace: true });
+        }
+        // 2. Resolve Tools
+        let tools = this.config.tools ?? ctor.tools;
+        if (typeof tools === "function") {
+            tools = tools(inputs);
+        }
+        if (Array.isArray(tools)) {
+            this.chat.withTools(tools, { replace: true });
+        }
+    }
+    // --- Fluent Configuration ---
+    /**
+     * Add instructions to the agent (replaces or appends).
+     */
+    withInstructions(instructions, options) {
+        this.chat.withInstructions(instructions, options);
+        return this;
+    }
+    /**
+     * Add tools to the agent.
+     */
+    withTools(tools, options) {
+        this.chat.withTools(tools, options);
+        return this;
+    }
+    /**
+     * Alias for withTools([tool]).
+     */
+    use(tool) {
+        return this.withTools([tool]);
+    }
     /**
      * Send a message to the agent and get a response.
-     * @param message - The user message
-     * @param options - Optional request options
      */
     async ask(message, options) {
+        if (options?.inputs) {
+            this.resolveLazyConfig(options.inputs);
+        }
         return this.chat.ask(message, options);
     }
+    /**
+     * Hook called when a tool call starts.
+     */
+    onToolCallStart(handler) {
+        this.chat.onToolCallStart(handler);
+        return this;
+    }
+    /**
+     * Hook called when a tool call ends.
+     */
+    onToolCallEnd(handler) {
+        this.chat.onToolCallEnd(handler);
+        return this;
+    }
+    /**
+     * Hook called when a tool call errors.
+     */
+    onToolCallError(handler) {
+        this.chat.onToolCallError(handler);
+        return this;
+    }
+    /**
+     * Hook called before a request.
+     */
+    beforeRequest(handler) {
+        this.chat.beforeRequest(handler);
+        return this;
+    }
+    /**
+     * Hook called after a response.
+     */
+    afterResponse(handler) {
+        this.chat.afterResponse(handler);
+        return this;
+    }
     /**
      * Alias for ask()
      */
@@ -207,10 +240,11 @@ export class Agent {
     }
     /**
      * Stream a response from the agent.
-     * @param message - The user message
-     * @param options - Optional request options
      */
     stream(message, options) {
+        if (options?.inputs) {
+            this.resolveLazyConfig(options.inputs);
+        }
         return this.chat.stream(message, options);
     }
     /**
@@ -240,19 +274,6 @@ export class Agent {
 }
 /**
  * Helper function to define an agent inline without creating a class.
- *
- * @example
- * ```typescript
- * const SupportAgent = defineAgent({
- *   model: "gpt-4o",
- *   instructions: "You are a helpful support agent",
- *   tools: [SearchDocs, LookupAccount],
- *   temperature: 0.2
- * });
- *
- * const agent = new SupportAgent();
- * const response = await agent.ask("Help me!");
- * ```
  */
 export function defineAgent(config) {
     return class extends Agent {