@voltagent/core 0.1.50 → 0.1.52

package/dist/index.d.ts

@@ -1102,6 +1102,11 @@ type AgentOptions = {
      * Sub-agents that this agent can delegate tasks to
      */
     subAgents?: any[];
+    /**
+     * Maximum number of steps (turns) the agent can take before stopping
+     * This overrides any supervisor config maxSteps setting
+     */
+    maxSteps?: number;
     /**
      * Optional user-defined context to be passed around
      */
@@ -1214,6 +1219,7 @@ interface CommonGenerateOptions {
     userId?: string;
     contextLimit?: number;
     tools?: BaseTool[];
+    maxSteps?: number;
     signal?: AbortSignal;
     historyEntryId?: string;
     operationContext?: OperationContext;
@@ -1227,7 +1233,7 @@ type PublicGenerateOptions = Omit<CommonGenerateOptions, "historyEntryId" | "ope
 /**
  * Agent status information
  */
-type AgentStatus = "idle" | "working" | "tool_calling" | "error" | "completed";
+type AgentStatus = "idle" | "working" | "error" | "completed" | "cancelled";
 /**
  * Tool call definition
  */
@@ -1322,6 +1328,15 @@ type AgentHandoffOptions = {
      * Parent's operation context to merge SubAgent steps into
      */
     parentOperationContext?: OperationContext;
+    /**
+     * 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
@@ -1380,6 +1395,8 @@ type OperationContext = {
     toolSpans?: Map<string, Span>;
     /** Conversation steps for building full message history including tool calls/results */
     conversationSteps?: StepWithContent[];
+    /** AbortSignal for cancelling the operation */
+    signal?: AbortSignal;
 };
 /**
  * Tool execution context passed to tool.execute method
@@ -1994,6 +2011,7 @@ type AgentStartEventMetadata = {
         stop?: string[];
         system?: string;
         toolChoice?: string;
+        maxSteps?: number;
     };
     systemPrompt?: string | BaseMessage | BaseMessage[];
     messages?: BaseMessage[];
@@ -2010,6 +2028,7 @@ interface AgentSuccessEventMetadata extends BaseEventMetadata {
         stop?: string[];
         system?: string;
         toolChoice?: string;
+        maxSteps?: number;
     };
 }
 interface MemoryEventMetadata extends BaseEventMetadata {
@@ -3196,7 +3215,7 @@ declare class SubAgentManager {
      * 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
@@ -3226,6 +3245,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
@@ -3293,6 +3313,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
      */
@@ -3434,6 +3458,10 @@ declare class Agent<TProvider extends {
      */
     private _endOtelToolSpan;
     private publishTimelineEvent;
+    /**
+     * Sets up abort signal listener for cancellation handling
+     */
+    private setupAbortSignalListener;
     /**
      * Create an enhanced fullStream with real-time SubAgent event injection
      */

package/dist/index.js

@@ -325,10 +325,6 @@ var BackgroundQueue = class {
       } catch (error) {
         lastError = error instanceof Error ? error : new Error(String(error));
         if (attempt < maxAttempts) {
-          import_dev.devLogger.warn(
-            `[Queue] Task ${task.id} failed (attempt ${attempt}/${maxAttempts}), retrying:`,
-            lastError.message
-          );
           await new Promise((resolve) => setTimeout(resolve, 50 * attempt));
         } else {
           import_dev.devLogger.error(
@@ -944,6 +940,10 @@ var GenerateOptionsSchema = import_zod_openapi.z.object({
   contextLimit: import_zod_openapi.z.number().int().positive().optional().default(10).openapi({
     description: "Optional limit for conversation history context"
   }),
+  maxSteps: import_zod_openapi.z.number().int().positive().optional().openapi({
+    description: "Maximum number of steps (turns) for this specific request (overrides agent's maxSteps)",
+    example: 5
+  }),
   temperature: import_zod_openapi.z.number().min(0).max(1).optional().default(0.7).openapi({ description: "Controls randomness (0-1)" }),
   maxTokens: import_zod_openapi.z.number().int().positive().optional().default(4e3).openapi({ description: "Maximum tokens to generate" }),
   topP: import_zod_openapi.z.number().min(0).max(1).optional().default(1).openapi({
@@ -1598,6 +1598,10 @@ app.openapi(streamRoute, async (c) => {
         temperature: 0.7
       }
     } = c.req.valid("json");
+    const abortController = new AbortController();
+    c.req.raw.signal?.addEventListener("abort", () => {
+      abortController.abort();
+    });
     const stream = new ReadableStream({
       async start(controller) {
         try {
@@ -1632,7 +1636,9 @@ app.openapi(streamRoute, async (c) => {
               temperature: options.temperature
               // Note: No onError callback needed - tool errors are handled via fullStream
               // Stream errors are handled by try/catch blocks around fullStream iteration
-            }
+            },
+            // Pass the abort signal to the agent
+            signal: abortController.signal
           };
           const response = await agent.streamText(input, processedStreamOptions);
           try {
@@ -1908,6 +1914,11 @@ app.openapi(streamObjectRoute, async (c) => {
       options = {}
     } = c.req.valid("json");
     const schemaInZodObject = (0, import_zod_from_json_schema.convertJsonSchemaToZod)(schema);
+    const abortController = new AbortController();
+    c.req.raw.signal?.addEventListener("abort", () => {
+      console.log("\u{1F6D1} API: Client aborted object stream request, stopping agent stream...");
+      abortController.abort();
+    });
     const sseStream = new ReadableStream({
       async start(controller) {
         try {
@@ -1954,7 +1965,9 @@ app.openapi(streamObjectRoute, async (c) => {
                 safeEnqueue(errorMessage);
                 safeClose();
               }
-            }
+            },
+            // Pass the abort signal to the agent
+            signal: abortController.signal
           };
           const agentStream = await agent.streamObject(
             input,
@@ -7606,7 +7619,10 @@ var SubAgentManager = class {
    * Calculate maximum number of steps based on sub-agents
    * More sub-agents means more potential steps
    */
-  calculateMaxSteps() {
+  calculateMaxSteps(agentMaxSteps) {
+    if (agentMaxSteps !== void 0) {
+      return agentMaxSteps;
+    }
     return this.subAgents.length > 0 ? 10 * this.subAgents.length : 10;
   }
   /**
@@ -7672,7 +7688,8 @@ ${agentsMemory || "No previous agent interactions available."}
       userId,
       parentAgentId,
       parentHistoryEntryId,
-      parentOperationContext
+      parentOperationContext,
+      maxSteps
     } = options;
     const context = options.context;
     const sourceAgent = options.sourceAgent;
@@ -7702,7 +7719,11 @@ Context: ${JSON.stringify(context, null, 2)}`;
         // @ts-expect-error - bad types
         parentAgentId: sourceAgent?.id || parentAgentId,
         parentHistoryEntryId,
-        parentOperationContext
+        parentOperationContext,
+        // Pass the abort signal from parent's operation context to subagent
+        signal: parentOperationContext?.signal,
+        // Pass maxSteps from parent to subagent (inherits parent's effective maxSteps)
+        maxSteps
       });
       let finalText = "";
       if (streamResponse.fullStream) {
@@ -7846,6 +7867,7 @@ Context: ${JSON.stringify(context, null, 2)}`;
       parentAgentId,
       parentHistoryEntryId,
       parentOperationContext,
+      maxSteps,
       ...restOptions
     } = options;
     const handoffConversationId = conversationId || crypto.randomUUID();
@@ -7858,7 +7880,8 @@ Context: ${JSON.stringify(context, null, 2)}`;
             conversationId: handoffConversationId,
             parentAgentId,
             parentHistoryEntryId,
-            parentOperationContext
+            parentOperationContext,
+            maxSteps
           });
         } catch (error) {
           import_dev15.devLogger.error(`Error in handoffToMultiple for agent ${agent.name}:`, error);
@@ -7885,7 +7908,14 @@ Context: ${JSON.stringify(context, null, 2)}`;
    * task to one or more specialized agents
    */
   createDelegateTool(options) {
-    const { sourceAgent, forwardEvent, operationContext, currentHistoryEntryId, ...restOptions } = options;
+    const {
+      sourceAgent,
+      forwardEvent,
+      operationContext,
+      currentHistoryEntryId,
+      maxSteps,
+      ...restOptions
+    } = options;
     return createTool({
       id: "delegate_task",
       name: "delegate_task",
@@ -7930,6 +7960,8 @@ Context: ${JSON.stringify(context, null, 2)}`;
             parentOperationContext: operationContext,
             // Pass the real-time event forwarder
             forwardEvent,
+            // Pass maxSteps from parent to subagents
+            maxSteps,
             ...restOptions
           });
           const structuredResults = results.map((result, index) => {
@@ -8035,6 +8067,10 @@ var Agent = class {
    * Indicates if the agent should format responses using Markdown.
    */
   markdown;
+  /**
+   * Maximum number of steps the agent can take before stopping
+   */
+  maxSteps;
   /**
    * Memory manager for the agent
    */
@@ -8077,6 +8113,7 @@ var Agent = class {
     this.retriever = options.retriever;
     this.voice = options.voice;
     this.markdown = options.markdown ?? false;
+    this.maxSteps = options.maxSteps;
     this.voltOpsClient = options.voltOpsClient;
     if (options.hooks) {
       this.hooks = options.hooks;
@@ -8329,7 +8366,7 @@ ${retrieverContext}`;
    * Calculate maximum number of steps based on sub-agents
    */
   calculateMaxSteps() {
-    return this.subAgentManager.calculateMaxSteps();
+    return this.subAgentManager.calculateMaxSteps(this.maxSteps);
   }
   /**
    * Prepare common options for text generation
@@ -8337,6 +8374,7 @@ ${retrieverContext}`;
   async prepareTextOptions(options = {}) {
     const {
       tools: dynamicTools,
+      maxSteps: optionsMaxSteps,
       historyEntryId,
       operationContext,
       internalStreamForwarder
@@ -8414,6 +8452,8 @@ ${retrieverContext}`;
         operationContext: options.operationContext,
         forwardEvent,
         // Pass the real-time event forwarder
+        // Pass effective maxSteps (options override or agent default)
+        maxSteps: optionsMaxSteps ?? this.calculateMaxSteps(),
         ...options
       });
       const delegateIndex = toolsToUse.findIndex((tool2) => tool2.name === "delegate_task");
@@ -8425,7 +8465,7 @@ ${retrieverContext}`;
     }
     return {
       tools: toolsToUse,
-      maxSteps: this.calculateMaxSteps()
+      maxSteps: optionsMaxSteps ?? this.calculateMaxSteps()
     };
   }
   /**
@@ -8469,7 +8509,9 @@ ${retrieverContext}`;
       parentHistoryEntryId: options.parentHistoryEntryId,
       otelSpan,
       // Use parent's conversationSteps if available (for SubAgents), otherwise create new array
-      conversationSteps: options.parentOperationContext?.conversationSteps || []
+      conversationSteps: options.parentOperationContext?.conversationSteps || [],
+      // Inherit signal from parent context or use provided signal
+      signal: options.parentOperationContext?.signal || options.signal
     };
     return opContext;
   }
@@ -8603,6 +8645,52 @@ ${retrieverContext}`;
       parentHistoryEntryId: operationContext.parentHistoryEntryId
     });
   }
+  /**
+   * Sets up abort signal listener for cancellation handling
+   */
+  setupAbortSignalListener(signal, operationContext, finalConversationId, agentStartEvent) {
+    if (!signal)
+      return;
+    signal.addEventListener("abort", async () => {
+      this.updateHistoryEntry(operationContext, {
+        status: "cancelled",
+        endTime: /* @__PURE__ */ new Date()
+      });
+      operationContext.isActive = false;
+      const cancellationError = new Error("Operation cancelled by user");
+      cancellationError.name = "AbortError";
+      const agentCancelledEvent = {
+        id: crypto.randomUUID(),
+        name: "agent:cancel",
+        type: "agent",
+        startTime: agentStartEvent.startTime,
+        endTime: (/* @__PURE__ */ new Date()).toISOString(),
+        level: "INFO",
+        input: null,
+        statusMessage: {
+          message: cancellationError.message,
+          code: "USER_CANCELLED",
+          stage: "cancelled"
+        },
+        status: "cancelled",
+        metadata: {
+          displayName: this.name,
+          id: this.id,
+          userContext: Object.fromEntries(operationContext.userContext.entries())
+        },
+        traceId: operationContext.historyEntry.id,
+        parentEventId: agentStartEvent.id
+      };
+      this.publishTimelineEvent(operationContext, agentCancelledEvent);
+      await this.hooks.onEnd?.({
+        agent: this,
+        output: void 0,
+        error: cancellationError,
+        conversationId: finalConversationId || "",
+        context: operationContext
+      });
+    });
+  }
   /**
    * Create an enhanced fullStream with real-time SubAgent event injection
    */
@@ -8659,7 +8747,8 @@ ${retrieverContext}`;
       parentHistoryEntryId,
       parentOperationContext,
       contextLimit = 10,
-      userContext
+      userContext,
+      signal
     } = internalOptions;
     const operationContext = await this.initializeHistory(input, "working", {
       parentAgentId,
@@ -8668,7 +8757,8 @@ ${retrieverContext}`;
       userContext,
       userId,
       conversationId: initialConversationId,
-      parentOperationContext
+      parentOperationContext,
+      signal
     });
     const { messages: contextMessages, conversationId: finalConversationId } = await this.memoryManager.prepareConversationContext(
       operationContext,
@@ -8719,7 +8809,8 @@ ${retrieverContext}`;
             temperature: internalOptions.provider?.temperature,
             topP: internalOptions.provider?.topP,
             frequencyPenalty: internalOptions.provider?.frequencyPenalty,
-            presencePenalty: internalOptions.provider?.presencePenalty
+            presencePenalty: internalOptions.provider?.presencePenalty,
+            maxSteps: internalOptions.maxSteps
           }
         },
         traceId: operationContext.historyEntry.id
@@ -8727,6 +8818,10 @@ ${retrieverContext}`;
       operationContext.userContext.set("agent_start_time", agentStartTime);
       operationContext.userContext.set("agent_start_event_id", agentStartEvent.id);
       this.publishTimelineEvent(operationContext, agentStartEvent);
+      this.setupAbortSignalListener(signal, operationContext, finalConversationId, {
+        id: agentStartEvent.id,
+        startTime: agentStartTime
+      });
       const onStepFinish = this.memoryManager.createStepFinishHandler(
         operationContext,
         userId,
@@ -8840,7 +8935,7 @@ ${retrieverContext}`;
                   id: crypto.randomUUID(),
                   name: "tool:success",
                   type: "tool",
-                  startTime: (/* @__PURE__ */ new Date()).toISOString(),
+                  startTime: toolStartInfo.startTime,
                   // Use the original start time
                   endTime: (/* @__PURE__ */ new Date()).toISOString(),
                   // Current time as end time
@@ -8904,7 +8999,8 @@ ${retrieverContext}`;
             temperature: internalOptions.provider?.temperature,
             topP: internalOptions.provider?.topP,
             frequencyPenalty: internalOptions.provider?.frequencyPenalty,
-            presencePenalty: internalOptions.provider?.presencePenalty
+            presencePenalty: internalOptions.provider?.presencePenalty,
+            maxSteps: internalOptions.maxSteps
           }
         },
         traceId: operationContext.historyEntry.id,
@@ -9015,7 +9111,8 @@ ${retrieverContext}`;
       parentHistoryEntryId,
       parentOperationContext,
       contextLimit = 10,
-      userContext
+      userContext,
+      signal
     } = internalOptions;
     const operationContext = await this.initializeHistory(input, "working", {
       parentAgentId,
@@ -9024,7 +9121,8 @@ ${retrieverContext}`;
       userContext,
       userId,
       conversationId: initialConversationId,
-      parentOperationContext
+      parentOperationContext,
+      signal
     });
     const { messages: contextMessages, conversationId: finalConversationId } = await this.memoryManager.prepareConversationContext(
       operationContext,
@@ -9073,7 +9171,8 @@ ${retrieverContext}`;
           temperature: internalOptions.provider?.temperature,
           topP: internalOptions.provider?.topP,
           frequencyPenalty: internalOptions.provider?.frequencyPenalty,
-          presencePenalty: internalOptions.provider?.presencePenalty
+          presencePenalty: internalOptions.provider?.presencePenalty,
+          maxSteps: internalOptions.maxSteps
         }
       },
       traceId: operationContext.historyEntry.id
@@ -9081,6 +9180,10 @@ ${retrieverContext}`;
     operationContext.userContext.set("agent_start_time", agentStartTime);
     operationContext.userContext.set("agent_start_event_id", agentStartEvent.id);
     this.publishTimelineEvent(operationContext, agentStartEvent);
+    this.setupAbortSignalListener(signal, operationContext, finalConversationId, {
+      id: agentStartEvent.id,
+      startTime: agentStartTime
+    });
     const onStepFinish = this.memoryManager.createStepFinishHandler(
       operationContext,
       userId,
@@ -9201,7 +9304,7 @@ ${retrieverContext}`;
                 id: crypto.randomUUID(),
                 name: "tool:error",
                 type: "tool",
-                startTime: (/* @__PURE__ */ new Date()).toISOString(),
+                startTime: toolStartInfo.startTime,
                 // Use the original start time
                 endTime: (/* @__PURE__ */ new Date()).toISOString(),
                 // Current time as end time
@@ -9225,7 +9328,7 @@ ${retrieverContext}`;
                 id: crypto.randomUUID(),
                 name: "tool:success",
                 type: "tool",
-                startTime: (/* @__PURE__ */ new Date()).toISOString(),
+                startTime: toolStartInfo.startTime,
                 // Use the original start time
                 endTime: (/* @__PURE__ */ new Date()).toISOString(),
                 // Current time as end time
@@ -9306,7 +9409,8 @@ ${retrieverContext}`;
               temperature: internalOptions.provider?.temperature,
               topP: internalOptions.provider?.topP,
               frequencyPenalty: internalOptions.provider?.frequencyPenalty,
-              presencePenalty: internalOptions.provider?.presencePenalty
+              presencePenalty: internalOptions.provider?.presencePenalty,
+              maxSteps: internalOptions.maxSteps
             }
           },
           traceId: operationContext.historyEntry.id,
@@ -9356,7 +9460,7 @@ ${retrieverContext}`;
               id: crypto.randomUUID(),
               name: "tool:error",
               type: "tool",
-              startTime: (/* @__PURE__ */ new Date()).toISOString(),
+              startTime: toolStartInfo.startTime,
               endTime: (/* @__PURE__ */ new Date()).toISOString(),
               status: "error",
               level: "ERROR",
@@ -9474,7 +9578,8 @@ ${retrieverContext}`;
       parentHistoryEntryId,
       parentOperationContext,
       contextLimit = 10,
-      userContext
+      userContext,
+      signal
     } = internalOptions;
     const operationContext = await this.initializeHistory(input, "working", {
       parentAgentId,
@@ -9483,7 +9588,8 @@ ${retrieverContext}`;
       userContext,
       userId,
       conversationId: initialConversationId,
-      parentOperationContext
+      parentOperationContext,
+      signal
     });
     const { messages: contextMessages, conversationId: finalConversationId } = await this.memoryManager.prepareConversationContext(
       operationContext,
@@ -9534,7 +9640,8 @@ ${retrieverContext}`;
             temperature: internalOptions.provider?.temperature,
             topP: internalOptions.provider?.topP,
             frequencyPenalty: internalOptions.provider?.frequencyPenalty,
-            presencePenalty: internalOptions.provider?.presencePenalty
+            presencePenalty: internalOptions.provider?.presencePenalty,
+            maxSteps: internalOptions.maxSteps
           }
         },
         traceId: operationContext.historyEntry.id
@@ -9542,6 +9649,10 @@ ${retrieverContext}`;
       operationContext.userContext.set("agent_start_time", agentStartTime);
       operationContext.userContext.set("agent_start_event_id", agentStartEvent.id);
       this.publishTimelineEvent(operationContext, agentStartEvent);
+      this.setupAbortSignalListener(signal, operationContext, finalConversationId, {
+        id: agentStartEvent.id,
+        startTime: agentStartTime
+      });
       const onStepFinish = this.memoryManager.createStepFinishHandler(
         operationContext,
         userId,
@@ -9603,7 +9714,8 @@ ${retrieverContext}`;
             temperature: internalOptions.provider?.temperature,
             topP: internalOptions.provider?.topP,
             frequencyPenalty: internalOptions.provider?.frequencyPenalty,
-            presencePenalty: internalOptions.provider?.presencePenalty
+            presencePenalty: internalOptions.provider?.presencePenalty,
+            maxSteps: internalOptions.maxSteps
           }
         },
         traceId: operationContext.historyEntry.id,
@@ -9716,7 +9828,8 @@ ${retrieverContext}`;
       parentOperationContext,
       provider,
       contextLimit = 10,
-      userContext
+      userContext,
+      signal
     } = internalOptions;
     const operationContext = await this.initializeHistory(input, "working", {
       parentAgentId,
@@ -9725,7 +9838,8 @@ ${retrieverContext}`;
       userContext,
       userId,
       conversationId: initialConversationId,
-      parentOperationContext
+      parentOperationContext,
+      signal
     });
     const { messages: contextMessages, conversationId: finalConversationId } = await this.memoryManager.prepareConversationContext(
       operationContext,
@@ -9774,7 +9888,8 @@ ${retrieverContext}`;
           temperature: internalOptions.provider?.temperature,
           topP: internalOptions.provider?.topP,
           frequencyPenalty: internalOptions.provider?.frequencyPenalty,
-          presencePenalty: internalOptions.provider?.presencePenalty
+          presencePenalty: internalOptions.provider?.presencePenalty,
+          maxSteps: internalOptions.maxSteps
         }
       },
       traceId: operationContext.historyEntry.id
@@ -9782,6 +9897,10 @@ ${retrieverContext}`;
     operationContext.userContext.set("agent_start_time", agentStartTime);
     operationContext.userContext.set("agent_start_event_id", agentStartEvent.id);
     this.publishTimelineEvent(operationContext, agentStartEvent);
+    this.setupAbortSignalListener(signal, operationContext, finalConversationId, {
+      id: agentStartEvent.id,
+      startTime: agentStartTime
+    });
     const onStepFinish = this.memoryManager.createStepFinishHandler(
       operationContext,
       userId,
@@ -9847,7 +9966,8 @@ ${retrieverContext}`;
                 temperature: internalOptions.provider?.temperature,
                 topP: internalOptions.provider?.topP,
                 frequencyPenalty: internalOptions.provider?.frequencyPenalty,
-                presencePenalty: internalOptions.provider?.presencePenalty
+                presencePenalty: internalOptions.provider?.presencePenalty,
+                maxSteps: internalOptions.maxSteps
               }
             },
             traceId: operationContext.historyEntry.id,