add agent API support (#588)

* offload agent to api

* changeset

* auto-add api key to options

Author: sameelarif

Diff for: .changeset/curly-rules-build.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+Added support for offloading agent tasks to the API.

Diff for: lib/api.ts

@@ -12,11 +12,13 @@ import { GotoOptions } from "../types/playwright";
 import {
   ActOptions,
   ActResult,
+  AgentConfig,
   ExtractOptions,
   ExtractResult,
   ObserveOptions,
   ObserveResult,
 } from "../types/stagehand";
+import { AgentExecuteOptions, AgentResult } from ".";
 
 export class StagehandAPI {
   private apiKey: string;
@@ -118,6 +120,16 @@ export class StagehandAPI {
     });
   }
 
+  async agentExecute(
+    agentConfig: AgentConfig,
+    executeOptions: AgentExecuteOptions,
+  ): Promise<AgentResult> {
+    return this.execute<AgentResult>({
+      method: "agentExecute",
+      args: { agentConfig, executeOptions },
+    });
+  }
+
   async end(): Promise<Response> {
     const url = `/sessions/${this.sessionId}/end`;
     return await this.request(url, {

Diff for: lib/index.ts

@@ -851,6 +851,32 @@ export class Stagehand {
           throw new Error("Instruction is required for agent execution");
         }
 
+        if (this.usingAPI) {
+          if (!this.apiClient) {
+            throw new Error(
+              "API client not initialized. Ensure that you have initialized Stagehand via `await stagehand.init()`.",
+            );
+          }
+
+          if (!options.options) {
+            options.options = {};
+          }
+
+          if (options.provider === "anthropic") {
+            options.options.apiKey = process.env.ANTHROPIC_API_KEY;
+          } else if (options.provider === "openai") {
+            options.options.apiKey = process.env.OPENAI_API_KEY;
+          }
+
+          if (!options.options.apiKey) {
+            throw new Error(
+              `API key not found for \`${options.provider}\` provider. Please set the ${options.provider === "anthropic" ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY"} environment variable or pass an apiKey in the options object.`,
+            );
+          }
+
+          return await this.apiClient.agentExecute(options, executeOptions);
+        }
+
         return await agentHandler.execute(executeOptions);
       },
     };

Diff for: types/api.ts

@@ -8,7 +8,7 @@ export interface StagehandAPIConstructorParams {
 }
 
 export interface ExecuteActionParams {
-  method: "act" | "extract" | "observe" | "navigate" | "end";
+  method: "act" | "extract" | "observe" | "navigate" | "end" | "agentExecute";
   args?: unknown;
   params?: unknown;
 }