Additional agent logging (#1104)

# why
To inform the user throughout the agent execution process

# what changed
Added logs to tool calls, and on the stagehand agent handler

# test plan
- [x] tested locally

Author: miguelg719

.changeset/fifty-windows-throw.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Fix logging for stagehand agent

lib/agent/tools/act.ts

@@ -8,15 +8,27 @@ export const createActTool = (stagehand: Stagehand, executionModel?: string) =>
     description: "Perform an action on the page (click, type)",
     parameters: z.object({
       action: z.string()
-        .describe(`Describe what to click, or type within in a short, specific phrase that mentions the element type. 
+        .describe(`Describe the click, type, fill, scroll action within in a short, specific phrase that mentions the element type. 
           Examples:
           - "click the Login button"
           - "click the language dropdown"
           - type "John" into the first name input
-          - type "Doe" into the last name input`),
+          - type "Doe" into the last name input.
+          When attempting to fill a field you can say 'fill the field x with the value y'.`),
     }),
     execute: async ({ action }) => {
       try {
+        stagehand.logger({
+          category: "agent",
+          message: `Agent calling tool: act`,
+          level: 1,
+          auxiliary: {
+            arguments: {
+              value: action,
+              type: "string",
+            },
+          },
+        });
         const builtPrompt = buildActObservePrompt(
           action,
           Object.values(SupportedPlaywrightAction),

lib/agent/tools/ariaTree.ts

@@ -8,6 +8,11 @@ export const createAriaTreeTool = (stagehand: Stagehand) =>
       "gets the accessibility (ARIA) tree from the current page. this is useful for understanding the page structure and accessibility features. it should provide full context of what is on the page",
     parameters: z.object({}),
     execute: async () => {
+      stagehand.logger({
+        category: "agent",
+        message: `Agent calling tool: ariaTree`,
+        level: 1,
+      });
       const { page_text } = await stagehand.page.extract();
       const pageUrl = stagehand.page.url();
 

lib/agent/tools/close.ts

@@ -6,11 +6,11 @@ export const createCloseTool = () =>
     description: "Complete the task and close",
     parameters: z.object({
       reasoning: z.string().describe("Summary of what was accomplished"),
-      taskComplete: z
+      success: z
         .boolean()
-        .describe("Whether the task was completed successfully"),
+        .describe("Whether the full goal of the task was a success or not"),
     }),
-    execute: async ({ reasoning, taskComplete }) => {
-      return { success: true, reasoning, taskComplete };
+    execute: async ({ reasoning, success }) => {
+      return { success, reasoning };
     },
   });

lib/agent/tools/extract.ts

@@ -70,6 +70,22 @@ export const createExtractTool = (
     }),
     execute: async ({ instruction, schema }) => {
       try {
+        stagehand.logger({
+          category: "agent",
+          message: `Agent calling tool: extract`,
+          level: 1,
+          auxiliary: {
+            arguments: {
+              value: instruction,
+              type: "string",
+            },
+            // TODO: check if we want to log this
+            schema: {
+              value: schema,
+              type: "object",
+            },
+          },
+        });
         // Evaluate the schema string to get the actual Zod schema
         const zodSchema = evaluateZodSchema(schema, logger);
 

lib/agent/tools/fillform.ts

@@ -49,6 +49,17 @@ export const createFillFormTool = (
     }),
 
     execute: async ({ fields }) => {
+      stagehand.logger({
+        category: "agent",
+        message: `Agent calling tool: fillForm`,
+        level: 1,
+        auxiliary: {
+          arguments: {
+            value: JSON.stringify(fields),
+            type: "object",
+          },
+        },
+      });
       const instruction = `Return observation results for the following actions: ${fields
         .map((field) => field.action)
         .join(", ")}`;

lib/agent/tools/goto.ts

@@ -10,6 +10,17 @@ export const createGotoTool = (stagehand: Stagehand) =>
     }),
     execute: async ({ url }) => {
       try {
+        stagehand.logger({
+          category: "agent",
+          message: `Agent calling tool: goto`,
+          level: 1,
+          auxiliary: {
+            arguments: {
+              value: url,
+              type: "string",
+            },
+          },
+        });
         await stagehand.page.goto(url, { waitUntil: "load" });
         return { success: true, url };
       } catch (error) {

lib/agent/tools/navback.ts

@@ -9,6 +9,11 @@ export const createNavBackTool = (stagehand: Stagehand) =>
       reasoning: z.string().describe("Why you're going back"),
     }),
     execute: async () => {
+      stagehand.logger({
+        category: "agent",
+        message: `Agent calling tool: navback`,
+        level: 1,
+      });
       await stagehand.page.goBack();
       return { success: true };
     },

lib/agent/tools/screenshot.ts

@@ -8,6 +8,11 @@ export const createScreenshotTool = (stagehand: Stagehand) =>
       "Takes a screenshot of the current page. Use this tool to learn where you are on the page, or to get context of elements on the page",
     parameters: z.object({}),
     execute: async () => {
+      stagehand.logger({
+        category: "agent",
+        message: `Agent calling tool: screenshot`,
+        level: 1,
+      });
       const screenshotBuffer = await stagehand.page.screenshot({
         fullPage: false,
         type: "jpeg",

lib/agent/tools/scroll.ts

@@ -10,6 +10,17 @@ export const createScrollTool = (stagehand: Stagehand) =>
       direction: z.enum(["up", "down"]).describe("Direction to scroll"),
     }),
     execute: async ({ pixels, direction }) => {
+      stagehand.logger({
+        category: "agent",
+        message: `Agent calling tool: scroll`,
+        level: 1,
+        auxiliary: {
+          arguments: {
+            value: JSON.stringify({ pixels, direction }),
+            type: "object",
+          },
+        },
+      });
       await stagehand.page.mouse.wheel(
         0,
         direction === "up" ? -pixels : pixels,