feat(tarko-agent): add onEachAgentLoopEnd hook (#1111)

Author: ulivz

multimodal/tarko/agent-interface/src/agent-instance.ts

@@ -164,3 +164,23 @@ export interface PrepareRequestResult {
   /** Modified tools array */
   tools: Tool[];
 }
+
+/**
+ * Context provided to the onEachAgentLoopEnd hook
+ */
+export interface EachAgentLoopEndContext {
+  /** Session identifier for this conversation */
+  sessionId: string;
+
+  /** Current iteration number (1-based) */
+  iteration: number;
+
+  /** Whether this iteration produced a final answer (no more tool calls) */
+  hasFinalAnswer: boolean;
+
+  /** Whether the loop will continue to next iteration */
+  willContinue: boolean;
+
+  /** The assistant message event from this iteration (if any) */
+  assistantEvent?: import('./agent-event-stream').AgentEventStream.AssistantMessageEvent;
+}

multimodal/tarko/agent-interface/src/agent.ts

@@ -15,6 +15,7 @@ import {
   LoopTerminationCheckResult,
   PrepareRequestContext,
   PrepareRequestResult,
+  EachAgentLoopEndContext,
 } from './agent-instance';
 import { AgentRunObjectOptions, AgentRunStreamingOptions } from './agent-run-options';
 import {
@@ -209,6 +210,18 @@ export interface IAgent<T extends AgentOptions = AgentOptions> {
    */
   onEachAgentLoopStart(sessionId: string): void | Promise<void>;
 
+  /**
+   * Hook called at the end of each agent loop iteration
+   *
+   * This method is invoked after each iteration of the agent loop completes,
+   * allowing derived classes to perform cleanup, logging, or state updates
+   * based on the iteration results.
+   *
+   * @param context The iteration end context including session info and results
+   * @returns A promise that resolves when post-iteration cleanup is complete
+   */
+  onEachAgentLoopEnd(context: EachAgentLoopEndContext): void | Promise<void>;
+
   /**
    * Hook called at the end of the agent's execution loop
    *
@@ -299,4 +312,4 @@ export interface IAgent<T extends AgentOptions = AgentOptions> {
   onPrepareRequest(
     context: PrepareRequestContext,
   ): Promise<PrepareRequestResult> | PrepareRequestResult;
-}
+}

multimodal/tarko/agent/src/agent/base-agent.ts

@@ -16,6 +16,7 @@ import {
   Tool,
   PrepareRequestContext,
   PrepareRequestResult,
+  EachAgentLoopEndContext,
 } from '@tarko/agent-interface';
 import { getLogger } from '@tarko/shared-utils';
 
@@ -153,6 +154,20 @@ export abstract class BaseAgent<T extends AgentOptions = AgentOptions> {
     // Derived classes can override to insert custom logic
   }
 
+  /**
+   * Hook called at the end of each agent loop iteration
+   * This method is invoked after each iteration of the agent loop completes,
+   * allowing derived classes to perform cleanup, logging, or state updates
+   * based on the iteration results
+   *
+   * @param context The iteration end context including session info and results
+   * @returns A promise that resolves when post-iteration cleanup is complete
+   */
+  public onEachAgentLoopEnd(context: EachAgentLoopEndContext): void | Promise<void> {
+    // Default implementation does nothing
+    // Derived classes can override to insert custom logic
+  }
+
   /**
    * Hook called before a tool is executed
    * This allows subclasses to intercept or modify tool calls before execution
@@ -343,4 +358,4 @@ export abstract class BaseAgent<T extends AgentOptions = AgentOptions> {
     // Default implementation: return all tools without modification
     return tools;
   }
-}
+}

multimodal/tarko/agent/src/agent/runner/loop-executor.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { AgentEventStream, ToolCallEngine } from '@tarko/agent-interface';
+import { AgentEventStream, ToolCallEngine, EachAgentLoopEndContext } from '@tarko/agent-interface';
 import { getLogger } from '@tarko/shared-utils';
 import { ResolvedModel } from '@tarko/model-provider';
 import { LLMProcessor } from './llm-processor';
@@ -152,10 +152,13 @@ export class LoopExecutor {
 
         // Check if we've reached a final answer
         const assistantEvents = this.eventStream.getEventsByType(['assistant_message']);
+        let currentAssistantEvent: AgentEventStream.AssistantMessageEvent | undefined;
+
         if (assistantEvents.length > 0) {
           const latestAssistantEvent = assistantEvents[
             assistantEvents.length - 1
           ] as AgentEventStream.AssistantMessageEvent;
+          currentAssistantEvent = latestAssistantEvent;
 
           if (!latestAssistantEvent.toolCalls || latestAssistantEvent.toolCalls.length === 0) {
             finalEvent = latestAssistantEvent;
@@ -165,6 +168,23 @@ export class LoopExecutor {
           }
         }
 
+        // FIXME: Create `iterationEndContext` on demand.
+        // Call the iteration end hook
+        try {
+          const iterationEndContext: EachAgentLoopEndContext = {
+            sessionId,
+            iteration,
+            hasFinalAnswer: finalEvent !== null,
+            willContinue: finalEvent === null && iteration < this.maxIterations - 1,
+            assistantEvent: currentAssistantEvent,
+          };
+
+          await Promise.resolve(this.agent.onEachAgentLoopEnd(iterationEndContext));
+          this.logger.debug(`[Agent] Post-iteration hook executed for iteration ${iteration}`);
+        } catch (error) {
+          this.logger.error(`[Agent] Error in post-iteration hook: ${error}`);
+        }
+
         this.logger.info(`[Iteration] ${iteration}/${this.maxIterations} completed`);
       }