@voltagent/core 0.1.51 → 0.1.53

package/dist/index.d.ts

@@ -807,6 +807,104 @@ declare function streamEventForwarder(event: StreamEvent, options: StreamEventFo
  */
 declare function createStreamEventForwarder(options: StreamEventForwarderOptions): (event: StreamEvent) => Promise<void>;
 
+/**
+ * Available methods for subagent execution
+ */
+type SubAgentMethod = "streamText" | "generateText" | "streamObject" | "generateObject";
+/**
+ * Base configuration for a subagent with specific method and options
+ */
+interface BaseSubAgentConfig {
+    /** The agent to be used as a subagent */
+    agent: Agent<any>;
+    /** Provider options for the specific method call */
+    options?: ProviderOptions;
+}
+/**
+ * Configuration for text-based subagent methods (streamText and generateText)
+ */
+interface TextSubAgentConfig extends BaseSubAgentConfig {
+    /** The method to use when calling the subagent */
+    method: "streamText" | "generateText";
+    /** Schema for object generation methods (optional for text methods) */
+    schema?: z.ZodType;
+}
+/**
+ * Configuration for object-based subagent methods (streamObject and generateObject)
+ */
+interface ObjectSubAgentConfig extends BaseSubAgentConfig {
+    /** The method to use when calling the subagent */
+    method: "streamObject" | "generateObject";
+    /** Schema for object generation methods (required for object methods) */
+    schema: z.ZodType;
+}
+/**
+ * Configuration for a subagent with specific method and options
+ * Schema is required for object generation methods (streamObject and generateObject)
+ */
+type SubAgentConfigObject = TextSubAgentConfig | ObjectSubAgentConfig;
+/**
+ * Union type for subagent configuration
+ * - Direct Agent instance (backward compatibility): defaults to streamText method
+ * - SubAgentConfigObject: allows specifying method, schema, and options
+ */
+type SubAgentConfig = Agent<any> | SubAgentConfigObject;
+/**
+ * Helper function to create a subagent configuration with specific method and options
+ * This provides a convenient API for configuring subagents with different execution methods
+ *
+ * @param config - The configuration object containing agent, method, and optional schema/options
+ * @returns A SubAgentConfigObject that can be used in the Agent constructor
+ *
+ * @example
+ * // Backward compatible - direct agent (uses streamText by default)
+ * const supervisorAgent = new Agent({
+ *   name: "Supervisor",
+ *   instructions: "...",
+ *   llm: myLLM,
+ *   subAgents: [myAgent] // <- This still works! Uses streamText by default
+ * });
+ *
+ * @example
+ * // New API - mixed usage
+ * const supervisorAgent = new Agent({
+ *   name: "Supervisor",
+ *   instructions: "...",
+ *   llm: myLLM,
+ *   subAgents: [
+ *     myAgent, // <- Direct agent, uses streamText
+ *     createSubagent({
+ *       agent: myAgent,
+ *       method: 'generateObject',
+ *       schema: z.object({ result: z.string() }) // <- Schema is required for generateObject
+ *     })
+ *   ]
+ * });
+ *
+ * @example
+ * // Create a subagent that uses generateText with custom options
+ * createSubagent({
+ *   agent: myAgent,
+ *   method: 'generateText',
+ *   options: { temperature: 0.7, maxTokens: 1000 }
+ *   // schema is optional for generateText
+ * })
+ *
+ * @example
+ * // Create a subagent that uses streamObject - schema is required
+ * createSubagent({
+ *   agent: myAgent,
+ *   method: 'streamObject',
+ *   schema: z.object({
+ *     progress: z.number(),
+ *     status: z.string()
+ *   }),
+ *   options: { temperature: 0.2 }
+ * })
+ */
+declare function createSubagent(config: TextSubAgentConfig): TextSubAgentConfig;
+declare function createSubagent(config: ObjectSubAgentConfig): ObjectSubAgentConfig;
+
 /**
  * VoltOps Client Type Definitions
  *
@@ -1065,6 +1163,26 @@ type ProviderOptions = {
     toolExecutionContext?: ToolExecutionContext;
     [key: string]: unknown;
 };
+/**
+ * Configuration for supervisor agents that have subagents
+ */
+type SupervisorConfig = {
+    /**
+     * Complete custom system message for the supervisor agent
+     * If provided, this completely replaces the default template
+     * Only agents memory section will be appended if includeAgentsMemory is true
+     */
+    systemMessage?: string;
+    /**
+     * Whether to include agents memory in the supervisor system message
+     * @default true
+     */
+    includeAgentsMemory?: boolean;
+    /**
+     * Additional custom guidelines for the supervisor agent
+     */
+    customGuidelines?: string[];
+};
 /**
  * Agent configuration options
  */
@@ -1099,9 +1217,10 @@ type AgentOptions = {
      */
     tools?: ToolsDynamicValue;
     /**
-     * Sub-agents that this agent can delegate tasks to
+     * Maximum number of steps (turns) the agent can take before stopping
+     * This overrides any supervisor config maxSteps setting
      */
-    subAgents?: any[];
+    maxSteps?: number;
     /**
      * Optional user-defined context to be passed around
      */
@@ -1120,6 +1239,14 @@ type AgentOptions = {
      * ✨ Benefits: Observability + prompt management + dynamic prompts from console
      */
     telemetryExporter?: VoltAgentExporter;
+    /**
+     * Sub-agents that this agent can delegate tasks to
+     */
+    subAgents?: SubAgentConfig[];
+    /**
+     * Configuration for supervisor behavior when subAgents are present
+     */
+    supervisorConfig?: SupervisorConfig;
 } & ({
     /**
      * @deprecated Use `instructions` instead.
@@ -1214,6 +1341,7 @@ interface CommonGenerateOptions {
     userId?: string;
     contextLimit?: number;
     tools?: BaseTool[];
+    maxSteps?: number;
     signal?: AbortSignal;
     historyEntryId?: string;
     operationContext?: OperationContext;
@@ -1326,6 +1454,11 @@ type AgentHandoffOptions = {
      * AbortSignal to cancel the handoff operation
      */
     signal?: AbortSignal;
+    /**
+     * Maximum number of steps for the subagent (inherited from parent or API call)
+     * If not provided, subagent will use its own maxSteps calculation
+     */
+    maxSteps?: number;
 };
 /**
  * Result of a handoff to another agent
@@ -2000,6 +2133,7 @@ type AgentStartEventMetadata = {
         stop?: string[];
         system?: string;
         toolChoice?: string;
+        maxSteps?: number;
     };
     systemPrompt?: string | BaseMessage | BaseMessage[];
     messages?: BaseMessage[];
@@ -2016,6 +2150,7 @@ interface AgentSuccessEventMetadata extends BaseEventMetadata {
         stop?: string[];
         system?: string;
         toolChoice?: string;
+        maxSteps?: number;
     };
 }
 interface MemoryEventMetadata extends BaseEventMetadata {
@@ -2719,9 +2854,13 @@ declare class LibSQLStorage implements Memory {
  */
 declare class MemoryManager {
     /**
-     * The memory storage instance
+     * The memory storage instance for conversations
+     */
+    private conversationMemory;
+    /**
+     * The memory storage instance for history (always available)
      */
-    private memory;
+    private historyMemory;
     /**
      * Memory configuration options
      */
@@ -2737,7 +2876,7 @@ declare class MemoryManager {
     /**
      * Creates a new MemoryManager
      */
-    constructor(resourceId: string, memory?: Memory | false, options?: MemoryOptions);
+    constructor(resourceId: string, memory?: Memory | false, options?: MemoryOptions, historyMemory?: Memory);
     /**
      * Create and publish a timeline event for memory operations using the queue
      *
@@ -2775,9 +2914,13 @@ declare class MemoryManager {
      */
     private saveCurrentInput;
     /**
-     * Get the memory instance
+     * Get the conversation memory instance
      */
     getMemory(): Memory | undefined;
+    /**
+     * Get the history memory instance
+     */
+    getHistoryMemory(): Memory;
     /**
      * Get the memory options
      */
@@ -3172,20 +3315,21 @@ declare class SubAgentManager {
      */
     private agentName;
     /**
-     * Sub-agents that the parent agent can delegate tasks to
+     * Sub-agent configurations that the parent agent can delegate tasks to
+     * Can be either direct Agent instances or SubAgentConfigObject instances
      */
-    private subAgents;
+    private subAgentConfigs;
     /**
      * Creates a new SubAgentManager instance
      *
      * @param agentName - The name of the agent that owns this sub-agent manager
-     * @param subAgents - Initial sub-agents to add
+     * @param subAgents - Initial sub-agent configurations to add
      */
-    constructor(agentName: string, subAgents?: Agent<any>[]);
+    constructor(agentName: string, subAgents?: SubAgentConfig[]);
     /**
      * Add a sub-agent that the parent agent can delegate tasks to
      */
-    addSubAgent(agent: Agent<any>): void;
+    addSubAgent(agentConfig: SubAgentConfig): void;
     /**
      * Remove a sub-agent
      */
@@ -3194,21 +3338,42 @@ declare class SubAgentManager {
      * Unregister all sub-agents when parent agent is destroyed
      */
     unregisterAllSubAgents(): void;
+    /**
+     * Helper method to extract agent ID from SubAgentConfig
+     */
+    private extractAgentId;
+    /**
+     * Helper method to extract agent instance from SubAgentConfig
+     */
+    private extractAgent;
+    /**
+     * Helper method to extract agent name from SubAgentConfig
+     */
+    private extractAgentName;
+    /**
+     * Helper method to extract agent purpose/instructions from SubAgentConfig
+     */
+    private extractAgentPurpose;
+    /**
+     * Type guard to check if a SubAgentConfig is a SubAgentConfigObject
+     */
+    private isSubAgentConfigObject;
     /**
      * Get all sub-agents
      */
-    getSubAgents(): Agent<any>[];
+    getSubAgents(): SubAgentConfig[];
     /**
      * Calculate maximum number of steps based on sub-agents
      * More sub-agents means more potential steps
      */
-    calculateMaxSteps(): number;
+    calculateMaxSteps(agentMaxSteps?: number): number;
     /**
      * Generate enhanced system message for supervisor role
-     * @param baseDescription - The base description of the agent
+     * @param baseInstructions - The base instructions of the agent
      * @param agentsMemory - Optional string containing formatted memory from previous agent interactions
+     * @param config - Optional supervisor configuration to customize the system message
      */
-    generateSupervisorSystemMessage(baseInstructions: string, agentsMemory?: string): string;
+    generateSupervisorSystemMessage(baseInstructions: string, agentsMemory?: string, config?: SupervisorConfig): string;
     /**
      * Check if the agent has sub-agents
      */
@@ -3221,7 +3386,7 @@ declare class SubAgentManager {
      * Hand off a task to multiple agents in parallel
      */
     handoffToMultiple(options: Omit<AgentHandoffOptions, "targetAgent"> & {
-        targetAgents: Agent<any>[];
+        targetAgents: SubAgentConfig[];
     }): Promise<AgentHandoffResult[]>;
     /**
      * Creates a tool that allows the supervisor agent to delegate a
@@ -3232,6 +3397,7 @@ declare class SubAgentManager {
         currentHistoryEntryId?: string;
         operationContext?: OperationContext;
         forwardEvent?: (event: StreamEvent) => Promise<void>;
+        maxSteps?: number;
     }, Record<string, any>>): BaseTool;
     /**
      * Get sub-agent details for API exposure
@@ -3299,6 +3465,10 @@ declare class Agent<TProvider extends {
      * Indicates if the agent should format responses using Markdown.
      */
     readonly markdown: boolean;
+    /**
+     * Maximum number of steps the agent can take before stopping
+     */
+    readonly maxSteps?: number;
     /**
      * Memory manager for the agent
      */
@@ -3324,12 +3494,16 @@ declare class Agent<TProvider extends {
      * Takes priority over global VoltOpsClient for prompt management
      */
     private readonly voltOpsClient?;
+    /**
+     * Supervisor configuration for agents with subagents
+     */
+    private readonly supervisorConfig?;
     /**
      * Create a new agent
      */
     constructor(options: AgentOptions & TProvider & {
         model: ModelDynamicValue<ModelType<TProvider>>;
-        subAgents?: Agent<any>[];
+        subAgents?: SubAgentConfig[];
         maxHistoryEntries?: number;
         hooks?: AgentHooks;
         retriever?: BaseRetriever;
@@ -3467,7 +3641,7 @@ declare class Agent<TProvider extends {
     /**
      * Add a sub-agent that this agent can delegate tasks to
      */
-    addSubAgent(agent: Agent<any>): void;
+    addSubAgent(agentConfig: SubAgentConfig): void;
     /**
      * Remove a sub-agent
      */
@@ -3491,7 +3665,7 @@ declare class Agent<TProvider extends {
     /**
      * Get all sub-agents
      */
-    getSubAgents(): Agent<any>[];
+    getSubAgents(): SubAgentConfig[];
     /**
      * Unregister this agent
      */
@@ -4520,6 +4694,10 @@ declare class VoltAgent {
      * Register an agent
      */
     registerAgent(agent: Agent<any>): void;
+    /**
+     * Helper method to extract Agent instance from SubAgentConfig
+     */
+    private extractAgentFromConfig;
     /**
      * Register multiple agents
      */
@@ -4556,4 +4734,4 @@ declare class VoltAgent {
     shutdownTelemetry(): Promise<void>;
 }
 
-export { Agent, AgentErrorEvent, AgentHistoryEntry, AgentHookOnEnd, AgentHookOnHandoff, AgentHookOnStart, AgentHookOnToolEnd, AgentHookOnToolStart, AgentHooks, AgentOptions, AgentRegistry, AgentResponse, AgentStartEvent, AgentStartEventMetadata, AgentSuccessEvent, AgentSuccessEventMetadata, AgentTool, AllowedVariableValue, AnyToolConfig, AsyncIterableStream, BaseEventMetadata, BaseLLMOptions, BaseMessage, BaseRetriever, BaseTimelineEvent, BaseTool, BaseToolCall, CachedPrompt, ClientInfo, Conversation, ConversationQueryOptions, CreateConversationInput, CreateReasoningToolsOptions, CustomEndpointDefinition, CustomEndpointError, CustomEndpointHandler, DEFAULT_INSTRUCTIONS, DataContent, DynamicValue, DynamicValueOptions, ErrorStreamPart, EventStatus, ExtractVariableNames, FEW_SHOT_EXAMPLES, FilePart, FinishStreamPart, GenerateObjectOptions, GenerateTextOptions, HTTPServerConfig, HistoryStatus, HttpMethod, VoltOpsClient$1 as IVoltOpsClient, ImagePart, InMemoryStorage, InferGenerateObjectResponse, InferGenerateTextResponse, InferMessage, InferModel, InferProviderParams, InferStreamResponse, InferTool, LLMProvider, LibSQLStorage, MCPClient, MCPClientConfig, MCPClientEvents, MCPConfiguration, MCPOptions, MCPServerConfig, MCPToolCall, MCPToolResult, Memory, MemoryEventMetadata, MemoryManager, MemoryMessage, MemoryOptions, MemoryReadErrorEvent, MemoryReadStartEvent, MemoryReadSuccessEvent, MemoryWriteErrorEvent, MemoryWriteStartEvent, MemoryWriteSuccessEvent, MessageContent, MessageFilterOptions, MessageRole, ModelToolCall, NewTimelineEvent, NextAction, NodeType, OnEndHookArgs, OnHandoffHookArgs, OnStartHookArgs, OnToolEndHookArgs, OnToolStartHookArgs, OperationContext, PackageUpdateInfo, PromptApiClient, PromptApiResponse, PromptCreator, PromptHelper, PromptReference, PromptTemplate, ProviderObjectResponse, ProviderObjectStreamResponse, ProviderParams, ProviderResponse, ProviderTextResponse, ProviderTextStreamResponse, ReadableStreamType, ReasoningStep, ReasoningStepSchema, ReasoningStreamPart, ReasoningToolExecuteOptions, RetrieveOptions, Retriever, RetrieverErrorEvent, RetrieverOptions, RetrieverStartEvent, RetrieverSuccessEvent, SSEServerConfig, ServerOptions, SourceStreamPart, StandardEventData, StandardTimelineEvent, StdioServerConfig, StepChunkCallback, StepFinishCallback, StepWithContent, StreamEventForwarderOptions, StreamObjectFinishResult, StreamObjectOnFinishCallback, StreamObjectOptions, StreamPart, StreamTextFinishResult, StreamTextOnFinishCallback, StreamTextOptions, StreamableHTTPServerConfig, TemplateVariables, TextDeltaStreamPart, TextPart, TimelineEventCoreLevel, TimelineEventCoreStatus, TimelineEventCoreType, Tool, ToolCall, ToolCallStreamPart, ToolErrorEvent, ToolErrorInfo, ToolExecuteOptions, ToolExecutionContext, ToolManager, ToolOptions, ToolResultStreamPart, ToolSchema, ToolStartEvent, ToolStatus, ToolStatusInfo, ToolSuccessEvent, Toolkit, ToolsetMap, ToolsetWithTools, TransportError, Usage, UsageInfo, Voice, VoiceEventData, VoiceEventType, VoiceMetadata, VoiceOptions, VoltAgent, VoltAgentError, VoltAgentExporter, VoltAgentExporterOptions, VoltAgentOptions, VoltOpsClient, VoltOpsClientOptions, VoltOpsPromptApiClient, VoltOpsPromptManager, VoltOpsPromptManagerImpl, checkForUpdates, createAsyncIterableStream, createHooks, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createSimpleTemplateEngine, createStreamEventForwarder, createTool, createToolkit, createVoltOpsClient, VoltAgent as default, getNodeTypeFromNodeId, registerCustomEndpoint, registerCustomEndpoints, safeJsonParse, serializeValueForDebug, streamEventForwarder, tool, updateAllPackages, updateSinglePackage, zodSchemaToJsonUI };
+export { Agent, AgentErrorEvent, AgentHistoryEntry, AgentHookOnEnd, AgentHookOnHandoff, AgentHookOnStart, AgentHookOnToolEnd, AgentHookOnToolStart, AgentHooks, AgentOptions, AgentRegistry, AgentResponse, AgentStartEvent, AgentStartEventMetadata, AgentSuccessEvent, AgentSuccessEventMetadata, AgentTool, AllowedVariableValue, AnyToolConfig, AsyncIterableStream, BaseEventMetadata, BaseLLMOptions, BaseMessage, BaseRetriever, BaseTimelineEvent, BaseTool, BaseToolCall, CachedPrompt, ClientInfo, Conversation, ConversationQueryOptions, CreateConversationInput, CreateReasoningToolsOptions, CustomEndpointDefinition, CustomEndpointError, CustomEndpointHandler, DEFAULT_INSTRUCTIONS, DataContent, DynamicValue, DynamicValueOptions, ErrorStreamPart, EventStatus, ExtractVariableNames, FEW_SHOT_EXAMPLES, FilePart, FinishStreamPart, GenerateObjectOptions, GenerateTextOptions, HTTPServerConfig, HistoryStatus, HttpMethod, VoltOpsClient$1 as IVoltOpsClient, ImagePart, InMemoryStorage, InferGenerateObjectResponse, InferGenerateTextResponse, InferMessage, InferModel, InferProviderParams, InferStreamResponse, InferTool, LLMProvider, LibSQLStorage, MCPClient, MCPClientConfig, MCPClientEvents, MCPConfiguration, MCPOptions, MCPServerConfig, MCPToolCall, MCPToolResult, Memory, MemoryEventMetadata, MemoryManager, MemoryMessage, MemoryOptions, MemoryReadErrorEvent, MemoryReadStartEvent, MemoryReadSuccessEvent, MemoryWriteErrorEvent, MemoryWriteStartEvent, MemoryWriteSuccessEvent, MessageContent, MessageFilterOptions, MessageRole, ModelToolCall, NewTimelineEvent, NextAction, NodeType, ObjectSubAgentConfig, OnEndHookArgs, OnHandoffHookArgs, OnStartHookArgs, OnToolEndHookArgs, OnToolStartHookArgs, OperationContext, PackageUpdateInfo, PromptApiClient, PromptApiResponse, PromptCreator, PromptHelper, PromptReference, PromptTemplate, ProviderObjectResponse, ProviderObjectStreamResponse, ProviderParams, ProviderResponse, ProviderTextResponse, ProviderTextStreamResponse, ReadableStreamType, ReasoningStep, ReasoningStepSchema, ReasoningStreamPart, ReasoningToolExecuteOptions, RetrieveOptions, Retriever, RetrieverErrorEvent, RetrieverOptions, RetrieverStartEvent, RetrieverSuccessEvent, SSEServerConfig, ServerOptions, SourceStreamPart, StandardEventData, StandardTimelineEvent, StdioServerConfig, StepChunkCallback, StepFinishCallback, StepWithContent, StreamEventForwarderOptions, StreamObjectFinishResult, StreamObjectOnFinishCallback, StreamObjectOptions, StreamPart, StreamTextFinishResult, StreamTextOnFinishCallback, StreamTextOptions, StreamableHTTPServerConfig, SubAgentConfig, SubAgentConfigObject, SubAgentMethod, TemplateVariables, TextDeltaStreamPart, TextPart, TextSubAgentConfig, TimelineEventCoreLevel, TimelineEventCoreStatus, TimelineEventCoreType, Tool, ToolCall, ToolCallStreamPart, ToolErrorEvent, ToolErrorInfo, ToolExecuteOptions, ToolExecutionContext, ToolManager, ToolOptions, ToolResultStreamPart, ToolSchema, ToolStartEvent, ToolStatus, ToolStatusInfo, ToolSuccessEvent, Toolkit, ToolsetMap, ToolsetWithTools, TransportError, Usage, UsageInfo, Voice, VoiceEventData, VoiceEventType, VoiceMetadata, VoiceOptions, VoltAgent, VoltAgentError, VoltAgentExporter, VoltAgentExporterOptions, VoltAgentOptions, VoltOpsClient, VoltOpsClientOptions, VoltOpsPromptApiClient, VoltOpsPromptManager, VoltOpsPromptManagerImpl, checkForUpdates, createAsyncIterableStream, createHooks, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createSimpleTemplateEngine, createStreamEventForwarder, createSubagent, createTool, createToolkit, createVoltOpsClient, VoltAgent as default, getNodeTypeFromNodeId, registerCustomEndpoint, registerCustomEndpoints, safeJsonParse, serializeValueForDebug, streamEventForwarder, tool, updateAllPackages, updateSinglePackage, zodSchemaToJsonUI };