refactor: update onEnd hook to use destructured arguments for improved readability

Author: omeraplak

examples/with-playwright/src/index.ts

@@ -29,18 +29,6 @@ import {
 } from "./tools";
 import { mistral } from "@ai-sdk/mistral";
 
-// Define the onEnd hook for browser cleanup
-const browserCleanupHook: AgentHooks["onEnd"] = async (
-  _agent: Agent<any>,
-  _outputOrError: any,
-  context: OperationContext,
-  _isError?: boolean,
-) => {
-  console.log(`[${context.operationId}] Operation finished. Cleaning up browser state...`);
-  // Call the reset function from the handler using the operation context
-  await resetBrowserStateInternal(context);
-};
-
 // Create a specialized agent for browsing
 export const browserAgent = new Agent({
   name: "Browser Agent",
@@ -49,7 +37,11 @@ export const browserAgent = new Agent({
   model: mistral("mistral-large-latest"),
 
   hooks: {
-    onEnd: browserCleanupHook,
+    onEnd: async ({ context }) => {
+      console.log(`[${context.operationId}] Operation finished. Cleaning up browser state...`);
+      // Call the reset function from the handler using the operation context
+      await resetBrowserStateInternal(context);
+    },
   },
   tools: [
     // Navigation tools

website/docs/agents/context.md

@@ -46,6 +46,7 @@ import {
   Agent,
   createHooks,
   createTool,
+  type OnEndHookArgs,
   type OperationContext,
   type ToolExecutionContext,
 } from "@voltagent/core";
@@ -69,7 +70,7 @@ async function ensurePage(context: OperationContext): Promise<Page> {
 
 // Hook for cleanup
 const hooks = createHooks({
-  onEnd: async (_agent, _result, context: OperationContext) => {
+  onEnd: async ({ context }: OnEndHookArgs) => {
     const browser = context.userContext.get(BROWSER_KEY) as Browser | undefined;
     if (browser) {
       console.log(`[${context.operationId}] Closing browser for context...`);
@@ -124,6 +125,8 @@ import {
   Agent,
   createHooks,
   createTool,
+  type OnStartHookArgs,
+  type OnEndHookArgs,
   type OperationContext,
   type ToolExecutionContext,
 } from "@voltagent/core";
@@ -133,13 +136,13 @@ import { openai } from "@ai-sdk/openai";
 
 // Define hooks that set and retrieve data
 const hooks = createHooks({
-  onStart: (agent: Agent<any>, context: OperationContext) => {
+  onStart: ({ agent, context }: OnStartHookArgs) => {
     // Set a unique request ID for this operation
     const requestId = `req-${Date.now()}`;
     context.userContext.set("requestId", requestId);
     console.log(`[${agent.name}] Operation started. RequestID: ${requestId}`);
   },
-  onEnd: (agent: Agent<any>, result: any, context: OperationContext) => {
+  onEnd: ({ agent, context }: OnEndHookArgs) => {
     // Retrieve the request ID at the end of the operation
     const requestId = context.userContext.get("requestId");
     console.log(`[${agent.name}] Operation finished. RequestID: ${requestId}`);
@@ -179,9 +182,3 @@ await agent.generateText(
 
 // Console output will show logs from onStart, the tool (if called), and onEnd,
 ```
-
-In this example:
-
-1.  The `onStart` hook generates a `requestId` and stores it in `userContext`.
-2.  If the LLM decides to use the `custom_context_logger` tool, the tool's `execute` function accesses the `requestId` from `userContext` via the `options.operationContext` provided to it.
-3.  The `onEnd` hook retrieves the same `requestId` from the context, demonstrating that the data persisted throughout the operation's lifecycle.

website/docs/agents/overview.md

@@ -272,41 +272,56 @@ console.log(response.text);
 
 **Why?** To observe and potentially intercept or modify the agent's behavior at various lifecycle stages (start, end, tool calls, etc.) for logging, debugging, or custom logic.
 
-Hooks are triggered at specific points during the execution of `generate*`/`stream*` methods.
+Hooks are triggered at specific points during the execution of `generate*`/`stream*` methods. Each hook receives a single argument object containing relevant information like the agent instance and operation context.
 
 ```ts
-import { Agent, createHooks } from "@voltagent/core";
+import {
+  Agent,
+  createHooks,
+  type OnStartHookArgs,
+  type OnEndHookArgs,
+  type OnToolStartHookArgs,
+  type OnToolEndHookArgs,
+} from "@voltagent/core";
 import { VercelAIProvider } from "@voltagent/vercel-ai";
 import { openai } from "@ai-sdk/openai";
 
 const hooks = createHooks({
   // Called when any agent interaction starts (generateText, streamText, etc.)
-  onStart: async (agentInstance) => {
-    console.log(`Agent ${agentInstance.name} starting interaction...`);
+  onStart: async ({ agent, context }: OnStartHookArgs) => {
+    console.log(`Agent ${agent.name} starting interaction... Context:`, context);
   },
-  // Called when the interaction successfully finishes
-  onEnd: async (agentInstance, result) => {
-    // Result format depends on the method called (e.g., { text: ..., usage: ... } for generateText)
-    console.log(
-      `Agent ${agentInstance.name} finished. Final output:`,
-      result.text || result.object
-    );
+  // Called when the interaction finishes (successfully or with an error)
+  onEnd: async ({ agent, output, error, context }: OnEndHookArgs) => {
+    if (error) {
+      console.error(`Agent ${agent.name} finished with error:`, error);
+    } else if (output) {
+      // Output format depends on the method called (e.g., { text: ..., usage: ... } for generateText)
+      console.log(
+        `Agent ${agent.name} finished successfully. Final output:`,
+        output.text ?? output.object // Access 'text' or 'object' based on the operation type
+      );
+    }
+    console.log("Finished context:", context);
   },
   // Called before a tool is executed
-  onToolStart: async (agentInstance, toolCall) => {
-    console.log(`Agent ${agentInstance.name} starting tool: ${toolCall.toolName}`);
-  },
-  // Called after a tool finishes execution
-  onToolEnd: async (agentInstance, toolResult) => {
-    console.log(
-      `Agent ${agentInstance.name} finished tool: ${toolResult.toolName}, Result:`,
-      toolResult.result
-    );
+  onToolStart: async ({ agent, tool, context }: OnToolStartHookArgs) => {
+    console.log(`Agent ${agent.name} starting tool: ${tool.name}. Context:`, context);
   },
-  // Called if an error occurs during the interaction
-  onError: async (agentInstance, error) => {
-    console.error(`Agent ${agentInstance.name} encountered an error:`, error);
+  // Called after a tool finishes execution (successfully or with an error)
+  onToolEnd: async ({ agent, tool, output, error, context }: OnToolEndHookArgs) => {
+    if (error) {
+      console.error(`Agent ${agent.name} failed tool: ${tool.name}. Error:`, error);
+    } else {
+      console.log(
+        `Agent ${agent.name} finished tool: ${tool.name}. Result:`,
+        output // Tool output is directly available
+      );
+    }
+    console.log("Tool context:", context);
   },
+  // Note: There is no top-level 'onError' hook. Errors are handled within onEnd and onToolEnd.
+  // The 'onHandoff' hook (not shown here) is called when control is passed between agents (e.g., sub-agents).
 });
 
 const agent = new Agent({