@voltagent/core 1.1.37 → 1.1.38

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ModelMessage, DataContent as DataContent$1, UserContent, AssistantContent, ToolContent, ProviderOptions as ProviderOptions$1 } from '@ai-sdk/provider-utils';
+import { ModelMessage, ToolCallOptions, DataContent as DataContent$1, UserContent, AssistantContent, ToolContent, ProviderOptions as ProviderOptions$1 } from '@ai-sdk/provider-utils';
 export { AssistantContent, FilePart, ImagePart, TextPart, ToolContent, UserContent } from '@ai-sdk/provider-utils';
 import { Tool as Tool$1, TextStreamPart, generateText, UIMessage, StreamTextResult, LanguageModel, CallSettings, Output, ToolSet, GenerateTextResult, GenerateObjectResult, AsyncIterableStream as AsyncIterableStream$1, CallWarning, LanguageModelUsage, FinishReason, EmbeddingModel } from 'ai';
 export { LanguageModel, Tool as VercelTool, hasToolCall, stepCountIs } from 'ai';
@@ -58,95 +58,164 @@ type Toolkit = {
  */
 declare const createToolkit: (options: Toolkit) => Toolkit;
 
-/**
- * Status of a tool at any given time
- */
-type ToolStatus = "idle" | "working" | "error" | "completed";
-/**
- * Tool status information
- */
-type ToolStatusInfo = {
-    name: string;
-    status: ToolStatus;
-    result?: any;
-    error?: any;
-    input?: any;
-    output?: any;
-    timestamp: Date;
-    parameters?: any;
-};
-/**
- * Manager class to handle all tool-related operations, including Toolkits.
- */
-declare class ToolManager {
+declare abstract class BaseToolManager<TItems extends AgentTool | Tool$1 | Toolkit = AgentTool | Tool$1 | Toolkit, TToolkitManager extends BaseToolManager<TItems, never> | never = BaseToolManager<TItems, never>> {
     /**
      * User tools managed by this manager.
      * Includes server-side and client-side tools (no server execute) managed separately from server-executable tools.
      */
-    private baseTools;
+    protected baseTools: Map<string, BaseTool>;
     /**
      * Provider-defined tools managed by providers
      */
-    private providerTools;
+    protected providerTools: Map<string, ProviderTool>;
     /**
      * Toolkits managed by this manager.
      */
-    private toolkits;
+    protected toolkits: Map<string, TToolkitManager>;
     /**
      * Logger instance
      */
-    private logger;
+    protected logger: Logger;
     /**
      * Creates a new ToolManager.
      * Accepts individual tools, provider-defined tools, and toolkits.
      */
-    constructor(items?: (AgentTool | Tool$1 | Toolkit)[], logger?: Logger);
+    protected constructor(items?: TItems[], logger?: Logger);
+    /** Not all inheritances of BaseToolManager support toolkits - thus this is abstract */
+    abstract addToolkit(toolkit: Toolkit): boolean;
+    /**
+     * Add multiple tools or toolkits to the manager.
+     */
+    addItems(items: TItems[]): void;
+    addStandaloneTool(tool: AgentTool | Tool$1): boolean;
+    /**
+     * Remove a standalone tool by name. Does not remove tools from toolkits.
+     * @returns true if the tool was removed, false if it wasn't found.
+     */
+    removeTool(toolName: string): boolean;
+    /**
+     * Remove a toolkit by name.
+     * @returns true if the toolkit was removed, false if it wasn't found.
+     */
+    removeToolkit(toolkitName: string): boolean;
     /**
      * Get all toolkits managed by this manager.
      */
-    getToolkits(): Toolkit[];
+    getToolkits(): TToolkitManager[];
+    /**
+     * Get standalone tools and standalone tools within toolkits as a flattened list.
+     */
+    getAllBaseTools(): BaseTool[];
     /**
      * Get provider-defined tools managed externally by providers.
      */
-    getProviderTools(): ProviderTool[];
-    addTool(tool: AgentTool | Tool$1): boolean;
-    hasTool(toolName: string): boolean;
+    getAllProviderTools(): ProviderTool[];
     /**
-     * Add multiple tools or toolkits to the manager.
+     * Get all kinds of tools, owned by this manager and inside toolkits as a flattened list.
+     * */
+    getAllTools(): (BaseTool | ProviderTool)[];
+    /**
+     * Get names of all tools (standalone and inside toolkits), deduplicated.
      */
-    addItems(items: (AgentTool | Tool$1 | Toolkit)[]): void;
+    getAllToolNames(): string[];
     /**
-     * Get all individual tools and tools within toolkits as a flattened list.
+     * Returns tools owned directly by this manager (standalone tools), excluding tools inside toolkits.
      */
-    getTools(): BaseTool[];
+    protected getStandaloneTools(): (BaseTool | ProviderTool)[];
     /**
-     * Add a toolkit to the manager.
-     * If a toolkit with the same name already exists, it will be replaced.
-     * Also checks if any tool within the toolkit conflicts with existing standalone tools or tools in other toolkits.
-     * @returns true if the toolkit was successfully added or replaced.
+     * Check if any tool with the given name exists in this manager or nested toolkits.
      */
-    addToolkit(toolkit: Toolkit): boolean;
-    findInToolkits(toolName: string): Tool | ProviderTool | false;
+    hasToolInAny(toolName: string): boolean;
+}
+
+declare class ToolkitManager extends BaseToolManager<AgentTool | Tool$1, never> {
+    readonly name: string;
     /**
-     * Remove a standalone tool by name. Does not remove tools from toolkits.
-     * @returns true if the tool was removed, false if it wasn't found.
+     * A brief description of what the toolkit does or what tools it contains.
+     * Optional.
      */
-    removeTool(toolName: string): boolean;
+    readonly description?: string | undefined;
     /**
-     * Remove a toolkit by name.
-     * @returns true if the toolkit was removed, false if it wasn't found.
+     * Shared instructions for the LLM on how to use the tools within this toolkit.
+     * These instructions are intended to be added to the system prompt if `addInstructions` is true.
+     * Optional.
      */
-    removeToolkit(toolkitName: string): boolean;
+    readonly instructions?: string | undefined;
+    /**
+     * Whether to automatically add the toolkit's `instructions` to the agent's system prompt.
+     * If true, the instructions from individual tools within this toolkit might be ignored
+     * by the Agent's system message generation logic to avoid redundancy.
+     * Defaults to false.
+     */
+    readonly addInstructions: boolean;
+    /**
+     * Constructor does not accept toolkits - only tools
+     * */
+    constructor(name: string, items?: (AgentTool | Tool$1)[], 
+    /**
+     * A brief description of what the toolkit does or what tools it contains.
+     * Optional.
+     */
+    description?: string | undefined, 
+    /**
+     * Shared instructions for the LLM on how to use the tools within this toolkit.
+     * These instructions are intended to be added to the system prompt if `addInstructions` is true.
+     * Optional.
+     */
+    instructions?: string | undefined, 
+    /**
+     * Whether to automatically add the toolkit's `instructions` to the agent's system prompt.
+     * If true, the instructions from individual tools within this toolkit might be ignored
+     * by the Agent's system message generation logic to avoid redundancy.
+     * Defaults to false.
+     */
+    addInstructions?: boolean, logger?: Logger);
+    /**
+     * Toolkits are not supported inside a ToolkitManager (toolkits contain tools only).
+     * Keep the same signature as BaseToolManager.addToolkit to preserve type compatibility,
+     * but implement as a no-op (or warn) so callers won't crash.
+     */
+    addToolkit(toolkit: Toolkit): boolean;
+}
+
+declare class ToolManager extends BaseToolManager<AgentTool | Tool$1 | Toolkit, ToolkitManager> {
+    /**
+     * Creates a new ToolManager.
+     * Accepts individual tools, provider-defined tools, and toolkits.
+     */
+    constructor(items?: (AgentTool | Tool$1 | Toolkit)[], logger?: Logger);
     /**
-     * Combine static base tools with runtime tools (includes tools from toolkits).
+     * Add a toolkit to the manager.
+     * If a toolkit with the same name already exists, it will be replaced.
+     * Also checks if any tool within the toolkit conflicts with existing standalone tools or tools in other toolkits.
+     * @returns true if the toolkit was successfully added or replaced.
      */
-    combineStaticAndRuntimeBaseTools(runtimeTools?: (BaseTool | Toolkit)[]): BaseTool[];
+    addToolkit(toolkit: Toolkit): boolean;
+    prepareToolsForExecution(createToolExecuteFunction: (tool: AgentTool) => (args: any, options?: ToolExecuteOptions) => Promise<any>): Record<string, any>;
     /**
      * Get agent's tools (including those in toolkits) for API exposure.
      */
     getToolsForApi(): ApiToolInfo[];
 }
 
+/**
+ * Status of a tool at any given time
+ */
+type ToolStatus = "idle" | "working" | "error" | "completed";
+/**
+ * Tool status information
+ */
+type ToolStatusInfo = {
+    name: string;
+    status: ToolStatus;
+    result?: any;
+    error?: any;
+    input?: any;
+    output?: any;
+    timestamp: Date;
+    parameters?: any;
+};
+
 /**
  * Tool definition compatible with Vercel AI SDK
  */
@@ -184,7 +253,7 @@ type ToolOptions<T extends ToolSchema = ToolSchema, O extends ToolSchema | undef
     /**
      * Function to execute when the tool is called
      */
-    execute?: (args: z.infer<T>, context?: OperationContext) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
+    execute?: (args: z.infer<T>, context?: OperationContext, options?: ToolExecuteOptions) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
 };
 /**
  * Tool class for defining tools that agents can use
@@ -218,7 +287,7 @@ declare class Tool<T extends ToolSchema = ToolSchema, O extends ToolSchema | und
     /**
      * Function to execute when the tool is called
      */
-    readonly execute?: (args: z.infer<T>, context?: OperationContext) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
+    readonly execute?: (args: z.infer<T>, context?: OperationContext, options?: ToolExecuteOptions) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
     /**
      * Whether this tool should be executed on the client side.
      * Returns true when no server-side execute handler is provided.
@@ -416,24 +485,23 @@ type MessageRole = "user" | "assistant" | "system" | "tool";
  */
 type BaseMessage = ModelMessage;
 type ToolSchema = z.ZodType;
-type ToolExecuteOptions = {
+type ToolExecuteOptions = ToolCallOptions & {
     /**
-     * Optional AbortController for cancelling the execution and accessing the signal
+     * Optional AbortController for cancelling the execution and accessing the signal.
+     * Prefer using the provided abortSignal, but we keep this for backward compatibility.
      */
     abortController?: AbortController;
     /**
-     * @deprecated Use abortController.signal instead. This field will be removed in a future version.
-     * Optional AbortSignal to abort the execution
+     * @deprecated Use abortController.signal or options.abortSignal instead. This field will be removed in a future version.
      */
     signal?: AbortSignal;
     /**
      * The operation context associated with the agent invocation triggering this tool execution.
-     * Provides access to operation-specific state like context.
-     * The context includes a logger with full execution context (userId, conversationId, executionId).
+     * Provides access to operation-specific state like context and logging metadata.
      */
     operationContext?: OperationContext;
     /**
-     * Additional options can be added in the future
+     * Additional options can be added in the future.
      */
     [key: string]: any;
 };
@@ -3390,6 +3458,7 @@ interface OnToolStartHookArgs {
     tool: AgentTool;
     context: OperationContext;
     args: any;
+    options?: ToolExecuteOptions;
 }
 interface OnToolEndHookArgs {
     agent: Agent;
@@ -3399,6 +3468,7 @@ interface OnToolEndHookArgs {
     /** The error if the tool execution failed. */
     error: VoltAgentError | AbortError | undefined;
     context: OperationContext;
+    options?: ToolExecuteOptions;
 }
 interface OnPrepareMessagesHookArgs {
     /** The messages that will be sent to the LLM (AI SDK UIMessage). */
@@ -4529,10 +4599,7 @@ declare class Agent {
      * Validate tool output against optional output schema.
      */
     private validateToolOutput;
-    /**
-     * Convert VoltAgent tools to AI SDK format with context injection
-     */
-    private convertTools;
+    private createToolExecutionFactory;
     /**
      * Create step handler for memory and hooks
      */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ModelMessage, DataContent as DataContent$1, UserContent, AssistantContent, ToolContent, ProviderOptions as ProviderOptions$1 } from '@ai-sdk/provider-utils';
+import { ModelMessage, ToolCallOptions, DataContent as DataContent$1, UserContent, AssistantContent, ToolContent, ProviderOptions as ProviderOptions$1 } from '@ai-sdk/provider-utils';
 export { AssistantContent, FilePart, ImagePart, TextPart, ToolContent, UserContent } from '@ai-sdk/provider-utils';
 import { Tool as Tool$1, TextStreamPart, generateText, UIMessage, StreamTextResult, LanguageModel, CallSettings, Output, ToolSet, GenerateTextResult, GenerateObjectResult, AsyncIterableStream as AsyncIterableStream$1, CallWarning, LanguageModelUsage, FinishReason, EmbeddingModel } from 'ai';
 export { LanguageModel, Tool as VercelTool, hasToolCall, stepCountIs } from 'ai';
@@ -58,95 +58,164 @@ type Toolkit = {
  */
 declare const createToolkit: (options: Toolkit) => Toolkit;
 
-/**
- * Status of a tool at any given time
- */
-type ToolStatus = "idle" | "working" | "error" | "completed";
-/**
- * Tool status information
- */
-type ToolStatusInfo = {
-    name: string;
-    status: ToolStatus;
-    result?: any;
-    error?: any;
-    input?: any;
-    output?: any;
-    timestamp: Date;
-    parameters?: any;
-};
-/**
- * Manager class to handle all tool-related operations, including Toolkits.
- */
-declare class ToolManager {
+declare abstract class BaseToolManager<TItems extends AgentTool | Tool$1 | Toolkit = AgentTool | Tool$1 | Toolkit, TToolkitManager extends BaseToolManager<TItems, never> | never = BaseToolManager<TItems, never>> {
     /**
      * User tools managed by this manager.
      * Includes server-side and client-side tools (no server execute) managed separately from server-executable tools.
      */
-    private baseTools;
+    protected baseTools: Map<string, BaseTool>;
     /**
      * Provider-defined tools managed by providers
      */
-    private providerTools;
+    protected providerTools: Map<string, ProviderTool>;
     /**
      * Toolkits managed by this manager.
      */
-    private toolkits;
+    protected toolkits: Map<string, TToolkitManager>;
     /**
      * Logger instance
      */
-    private logger;
+    protected logger: Logger;
     /**
      * Creates a new ToolManager.
      * Accepts individual tools, provider-defined tools, and toolkits.
      */
-    constructor(items?: (AgentTool | Tool$1 | Toolkit)[], logger?: Logger);
+    protected constructor(items?: TItems[], logger?: Logger);
+    /** Not all inheritances of BaseToolManager support toolkits - thus this is abstract */
+    abstract addToolkit(toolkit: Toolkit): boolean;
+    /**
+     * Add multiple tools or toolkits to the manager.
+     */
+    addItems(items: TItems[]): void;
+    addStandaloneTool(tool: AgentTool | Tool$1): boolean;
+    /**
+     * Remove a standalone tool by name. Does not remove tools from toolkits.
+     * @returns true if the tool was removed, false if it wasn't found.
+     */
+    removeTool(toolName: string): boolean;
+    /**
+     * Remove a toolkit by name.
+     * @returns true if the toolkit was removed, false if it wasn't found.
+     */
+    removeToolkit(toolkitName: string): boolean;
     /**
      * Get all toolkits managed by this manager.
      */
-    getToolkits(): Toolkit[];
+    getToolkits(): TToolkitManager[];
+    /**
+     * Get standalone tools and standalone tools within toolkits as a flattened list.
+     */
+    getAllBaseTools(): BaseTool[];
     /**
      * Get provider-defined tools managed externally by providers.
      */
-    getProviderTools(): ProviderTool[];
-    addTool(tool: AgentTool | Tool$1): boolean;
-    hasTool(toolName: string): boolean;
+    getAllProviderTools(): ProviderTool[];
     /**
-     * Add multiple tools or toolkits to the manager.
+     * Get all kinds of tools, owned by this manager and inside toolkits as a flattened list.
+     * */
+    getAllTools(): (BaseTool | ProviderTool)[];
+    /**
+     * Get names of all tools (standalone and inside toolkits), deduplicated.
      */
-    addItems(items: (AgentTool | Tool$1 | Toolkit)[]): void;
+    getAllToolNames(): string[];
     /**
-     * Get all individual tools and tools within toolkits as a flattened list.
+     * Returns tools owned directly by this manager (standalone tools), excluding tools inside toolkits.
      */
-    getTools(): BaseTool[];
+    protected getStandaloneTools(): (BaseTool | ProviderTool)[];
     /**
-     * Add a toolkit to the manager.
-     * If a toolkit with the same name already exists, it will be replaced.
-     * Also checks if any tool within the toolkit conflicts with existing standalone tools or tools in other toolkits.
-     * @returns true if the toolkit was successfully added or replaced.
+     * Check if any tool with the given name exists in this manager or nested toolkits.
      */
-    addToolkit(toolkit: Toolkit): boolean;
-    findInToolkits(toolName: string): Tool | ProviderTool | false;
+    hasToolInAny(toolName: string): boolean;
+}
+
+declare class ToolkitManager extends BaseToolManager<AgentTool | Tool$1, never> {
+    readonly name: string;
     /**
-     * Remove a standalone tool by name. Does not remove tools from toolkits.
-     * @returns true if the tool was removed, false if it wasn't found.
+     * A brief description of what the toolkit does or what tools it contains.
+     * Optional.
      */
-    removeTool(toolName: string): boolean;
+    readonly description?: string | undefined;
     /**
-     * Remove a toolkit by name.
-     * @returns true if the toolkit was removed, false if it wasn't found.
+     * Shared instructions for the LLM on how to use the tools within this toolkit.
+     * These instructions are intended to be added to the system prompt if `addInstructions` is true.
+     * Optional.
      */
-    removeToolkit(toolkitName: string): boolean;
+    readonly instructions?: string | undefined;
+    /**
+     * Whether to automatically add the toolkit's `instructions` to the agent's system prompt.
+     * If true, the instructions from individual tools within this toolkit might be ignored
+     * by the Agent's system message generation logic to avoid redundancy.
+     * Defaults to false.
+     */
+    readonly addInstructions: boolean;
+    /**
+     * Constructor does not accept toolkits - only tools
+     * */
+    constructor(name: string, items?: (AgentTool | Tool$1)[], 
+    /**
+     * A brief description of what the toolkit does or what tools it contains.
+     * Optional.
+     */
+    description?: string | undefined, 
+    /**
+     * Shared instructions for the LLM on how to use the tools within this toolkit.
+     * These instructions are intended to be added to the system prompt if `addInstructions` is true.
+     * Optional.
+     */
+    instructions?: string | undefined, 
+    /**
+     * Whether to automatically add the toolkit's `instructions` to the agent's system prompt.
+     * If true, the instructions from individual tools within this toolkit might be ignored
+     * by the Agent's system message generation logic to avoid redundancy.
+     * Defaults to false.
+     */
+    addInstructions?: boolean, logger?: Logger);
+    /**
+     * Toolkits are not supported inside a ToolkitManager (toolkits contain tools only).
+     * Keep the same signature as BaseToolManager.addToolkit to preserve type compatibility,
+     * but implement as a no-op (or warn) so callers won't crash.
+     */
+    addToolkit(toolkit: Toolkit): boolean;
+}
+
+declare class ToolManager extends BaseToolManager<AgentTool | Tool$1 | Toolkit, ToolkitManager> {
+    /**
+     * Creates a new ToolManager.
+     * Accepts individual tools, provider-defined tools, and toolkits.
+     */
+    constructor(items?: (AgentTool | Tool$1 | Toolkit)[], logger?: Logger);
     /**
-     * Combine static base tools with runtime tools (includes tools from toolkits).
+     * Add a toolkit to the manager.
+     * If a toolkit with the same name already exists, it will be replaced.
+     * Also checks if any tool within the toolkit conflicts with existing standalone tools or tools in other toolkits.
+     * @returns true if the toolkit was successfully added or replaced.
      */
-    combineStaticAndRuntimeBaseTools(runtimeTools?: (BaseTool | Toolkit)[]): BaseTool[];
+    addToolkit(toolkit: Toolkit): boolean;
+    prepareToolsForExecution(createToolExecuteFunction: (tool: AgentTool) => (args: any, options?: ToolExecuteOptions) => Promise<any>): Record<string, any>;
     /**
      * Get agent's tools (including those in toolkits) for API exposure.
      */
     getToolsForApi(): ApiToolInfo[];
 }
 
+/**
+ * Status of a tool at any given time
+ */
+type ToolStatus = "idle" | "working" | "error" | "completed";
+/**
+ * Tool status information
+ */
+type ToolStatusInfo = {
+    name: string;
+    status: ToolStatus;
+    result?: any;
+    error?: any;
+    input?: any;
+    output?: any;
+    timestamp: Date;
+    parameters?: any;
+};
+
 /**
  * Tool definition compatible with Vercel AI SDK
  */
@@ -184,7 +253,7 @@ type ToolOptions<T extends ToolSchema = ToolSchema, O extends ToolSchema | undef
     /**
      * Function to execute when the tool is called
      */
-    execute?: (args: z.infer<T>, context?: OperationContext) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
+    execute?: (args: z.infer<T>, context?: OperationContext, options?: ToolExecuteOptions) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
 };
 /**
  * Tool class for defining tools that agents can use
@@ -218,7 +287,7 @@ declare class Tool<T extends ToolSchema = ToolSchema, O extends ToolSchema | und
     /**
      * Function to execute when the tool is called
      */
-    readonly execute?: (args: z.infer<T>, context?: OperationContext) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
+    readonly execute?: (args: z.infer<T>, context?: OperationContext, options?: ToolExecuteOptions) => Promise<O extends ToolSchema ? z.infer<O> : unknown>;
     /**
      * Whether this tool should be executed on the client side.
      * Returns true when no server-side execute handler is provided.
@@ -416,24 +485,23 @@ type MessageRole = "user" | "assistant" | "system" | "tool";
  */
 type BaseMessage = ModelMessage;
 type ToolSchema = z.ZodType;
-type ToolExecuteOptions = {
+type ToolExecuteOptions = ToolCallOptions & {
     /**
-     * Optional AbortController for cancelling the execution and accessing the signal
+     * Optional AbortController for cancelling the execution and accessing the signal.
+     * Prefer using the provided abortSignal, but we keep this for backward compatibility.
      */
     abortController?: AbortController;
     /**
-     * @deprecated Use abortController.signal instead. This field will be removed in a future version.
-     * Optional AbortSignal to abort the execution
+     * @deprecated Use abortController.signal or options.abortSignal instead. This field will be removed in a future version.
      */
     signal?: AbortSignal;
     /**
      * The operation context associated with the agent invocation triggering this tool execution.
-     * Provides access to operation-specific state like context.
-     * The context includes a logger with full execution context (userId, conversationId, executionId).
+     * Provides access to operation-specific state like context and logging metadata.
      */
     operationContext?: OperationContext;
     /**
-     * Additional options can be added in the future
+     * Additional options can be added in the future.
      */
     [key: string]: any;
 };
@@ -3390,6 +3458,7 @@ interface OnToolStartHookArgs {
     tool: AgentTool;
     context: OperationContext;
     args: any;
+    options?: ToolExecuteOptions;
 }
 interface OnToolEndHookArgs {
     agent: Agent;
@@ -3399,6 +3468,7 @@ interface OnToolEndHookArgs {
     /** The error if the tool execution failed. */
     error: VoltAgentError | AbortError | undefined;
     context: OperationContext;
+    options?: ToolExecuteOptions;
 }
 interface OnPrepareMessagesHookArgs {
     /** The messages that will be sent to the LLM (AI SDK UIMessage). */
@@ -4529,10 +4599,7 @@ declare class Agent {
      * Validate tool output against optional output schema.
      */
     private validateToolOutput;
-    /**
-     * Convert VoltAgent tools to AI SDK format with context injection
-     */
-    private convertTools;
+    private createToolExecutionFactory;
     /**
      * Create step handler for memory and hooks
      */