fix: resolve dotenv loading in examples and tests

.changeset/cuddly-owls-battle.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+add logger param to external aisdk client

.changeset/gentle-beds-enjoy.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Add haiku 4.5 computer use support

.changeset/nice-dogs-march.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+patch stagehand agent api support

.changeset/quick-clouds-kick.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+update cua agents key & system prompt handling

.changeset/upset-ideas-fall.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Add pageUrl & timestamp to agent actions

.gitignore

@@ -1,3 +1,4 @@
+CLAUDE.md
 node_modules/
 /test-results/
 /playwright-report/

CHANGELOG.md

@@ -1,5 +1,43 @@
 # @browserbasehq/stagehand
 
+## 2.5.2
+
+### Patch Changes
+
+- [#1114](https://github.com/browserbase/stagehand/pull/1114) [`c0fbc51`](https://github.com/browserbase/stagehand/commit/c0fbc51a4b7e0b803af254501d2f89473124f0dc) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - configure default viewport when running on browserbase
+
+## 2.5.1
+
+### Patch Changes
+
+- [#1082](https://github.com/browserbase/stagehand/pull/1082) [`8c0fd01`](https://github.com/browserbase/stagehand/commit/8c0fd01c965a809b96c026f4674685e6445bc7d4) Thanks [@tkattkat](https://github.com/tkattkat)! - Pass stagehand object to agent instead of stagehand page
+
+- [#1104](https://github.com/browserbase/stagehand/pull/1104) [`a1ad06c`](https://github.com/browserbase/stagehand/commit/a1ad06c5398db10db7a2a83075b808dc63a963f7) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix logging for stagehand agent
+
+- [#1066](https://github.com/browserbase/stagehand/pull/1066) [`9daa584`](https://github.com/browserbase/stagehand/commit/9daa58477111e1470f2b618a898738b5e1967cb6) Thanks [@tkattkat](https://github.com/tkattkat)! - Add playwright arguments to agent execute response
+
+- [#1077](https://github.com/browserbase/stagehand/pull/1077) [`7f38b3a`](https://github.com/browserbase/stagehand/commit/7f38b3a3048ba28f81649c33c0d633c4853146bd) Thanks [@tkattkat](https://github.com/tkattkat)! - adds support for stagehand agent in the api
+
+- [#1032](https://github.com/browserbase/stagehand/pull/1032) [`bf2d0e7`](https://github.com/browserbase/stagehand/commit/bf2d0e79da744b6b2a82d60e1ad05ca9fa811488) Thanks [@miguelg719](https://github.com/miguelg719)! - Fix for zod peer dependency support
+
+- [#1014](https://github.com/browserbase/stagehand/pull/1014) [`6966201`](https://github.com/browserbase/stagehand/commit/6966201e2511eb897132d237d0b7712b48b3c7ab) Thanks [@tkattkat](https://github.com/tkattkat)! - Replace operator handler with base of new agent
+
+- [#1089](https://github.com/browserbase/stagehand/pull/1089) [`536f366`](https://github.com/browserbase/stagehand/commit/536f366f868d115ffa84c2c92124ae05400dd8be) Thanks [@miguelg719](https://github.com/miguelg719)! - Fixed info logs on api session create
+
+- [#1103](https://github.com/browserbase/stagehand/pull/1103) [`889cb6c`](https://github.com/browserbase/stagehand/commit/889cb6cec27f0fc07286a9263bdc4d559149a037) Thanks [@tkattkat](https://github.com/tkattkat)! - patch custom tool support in anthropic cua client
+
+- [#1056](https://github.com/browserbase/stagehand/pull/1056) [`6a002b2`](https://github.com/browserbase/stagehand/commit/6a002b234dbf1ac7d1f180eeffdf66154fa7799b) Thanks [@chrisreadsf](https://github.com/chrisreadsf)! - remove need for duplicate project id if already passed to Stagehand
+
+- [#1090](https://github.com/browserbase/stagehand/pull/1090) [`8ff5c5a`](https://github.com/browserbase/stagehand/commit/8ff5c5a4b2050fc581240ae1befcdc0cf9195873) Thanks [@miguelg719](https://github.com/miguelg719)! - Improve failed act error logs
+
+- [#1014](https://github.com/browserbase/stagehand/pull/1014) [`6966201`](https://github.com/browserbase/stagehand/commit/6966201e2511eb897132d237d0b7712b48b3c7ab) Thanks [@tkattkat](https://github.com/tkattkat)! - replace operator agent with scaffold for new stagehand agent
+
+- [#1107](https://github.com/browserbase/stagehand/pull/1107) [`3ccf335`](https://github.com/browserbase/stagehand/commit/3ccf335d943b43cd5249e4eeb5b1a8f2aff7fd3b) Thanks [@seanmcguire12](https://github.com/seanmcguire12)! - fix: url extraction not working inside an array
+
+- [#1102](https://github.com/browserbase/stagehand/pull/1102) [`a99aa48`](https://github.com/browserbase/stagehand/commit/a99aa48936ae3ce113172bce673809eaf5ef7ac1) Thanks [@miguelg719](https://github.com/miguelg719)! - Add current page and date context to agent
+
+- [#1110](https://github.com/browserbase/stagehand/pull/1110) [`dda52f1`](https://github.com/browserbase/stagehand/commit/dda52f170de0bbbb6e9e684b2b0fa7c53fbe2ab9) Thanks [@miguelg719](https://github.com/miguelg719)! - Add support for new Gemini Computer Use models
+
 ## 2.5.0
 
 ### Minor Changes
@@ -233,15 +271,13 @@
   We're thrilled to announce the release of Stagehand 2.0, bringing significant improvements to make browser automation more powerful, faster, and easier to use than ever before.
 
   ### 🚀 New Features
-
   - **Introducing `stagehand.agent`**: A powerful new way to integrate SOTA Computer use models or Browserbase's [Open Operator](https://operator.browserbase.com) into Stagehand with one line of code! Perfect for multi-step workflows and complex interactions. [Learn more](https://docs.stagehand.dev/concepts/agent)
   - **Lightning-fast `act` and `extract`**: Major performance improvements to make your automations run significantly faster.
   - **Enhanced Logging**: Better visibility into what's happening during automation with improved logging and debugging capabilities.
   - **Comprehensive Documentation**: A completely revamped documentation site with better examples, guides, and best practices.
   - **Improved Error Handling**: More descriptive errors and better error recovery to help you debug issues faster.
 
   ### 🛠️ Developer Experience
-
   - **Better TypeScript Support**: Enhanced type definitions and better IDE integration
   - **Better Error Messages**: Clearer, more actionable error messages to help you debug faster
   - **Improved Caching**: More reliable action caching for better performance
@@ -502,7 +538,6 @@
 - [#316](https://github.com/browserbase/stagehand/pull/316) [`902e633`](https://github.com/browserbase/stagehand/commit/902e633e126a58b80b757ea0ecada01a7675a473) Thanks [@kamath](https://github.com/kamath)! - rename browserbaseResumeSessionID -> browserbaseSessionID
 
 - [#296](https://github.com/browserbase/stagehand/pull/296) [`f11da27`](https://github.com/browserbase/stagehand/commit/f11da27a20409c240ceeea2003d520f676def61a) Thanks [@kamath](https://github.com/kamath)! - - Deprecate fields in `init` in favor of constructor options
-
   - Deprecate `initFromPage` in favor of `browserbaseResumeSessionID` in constructor
   - Rename `browserBaseSessionCreateParams` -> `browserbaseSessionCreateParams`
 

README.md

@@ -100,7 +100,7 @@ Visit [docs.stagehand.dev](https://docs.stagehand.dev) to view the full document
 
 ## Getting Started
 
-Start with Stagehand with one line of code, or check out our [Quickstart Guide](https://docs.stagehand.dev/get_started/quickstart) for more information:
+Start with Stagehand with one line of code, or check out our [Quickstart Guide](https://docs.stagehand.dev/first-steps/quickstart) for more information:
 
 ```bash
 npx create-browser-app

docs/basics/agent.mdx

@@ -30,28 +30,28 @@ There are two ways to create agents in Stagehand:
 
 ### Computer Use Agents
 
-Use computer use agents with specialized models from OpenAI or Anthropic: 
+Use computer use agents with specialized models from OpenAI, Anthropic, or Google: 
 
 <CodeGroup>
 ```typescript TypeScript
 const agent = stagehand.agent({
-  provider: "anthropic",
-  model: "claude-sonnet-4-20250514",
+  provider: "google",
+  model: "gemini-2.5-computer-use-preview-10-2025",
   instructions: "You are a helpful assistant that can use a web browser.",
   options: {
-    apiKey: process.env.ANTHROPIC_API_KEY,
+    apiKey: process.env.GOOGLE_API_KEY,
   },
 });
 await agent.execute("apply for a job at Browserbase")
 ```
 
 ```python Python
 agent = stagehand.agent({
-    "provider": "anthropic",
-    "model": "claude-sonnet-4-20250514",
+    "provider": "google",
+    "model": "gemini-2.5-computer-use-preview-10-2025",
     "instructions": "You are a helpful assistant that can use a web browser.",
     "options": {
-      "apiKey": os.getenv("ANTHROPIC_API_KEY"),
+      "apiKey": os.getenv("GOOGLE_API_KEY"),
     },
 })
 await agent.execute("apply for a job at Browserbase")
@@ -77,14 +77,14 @@ Agents can be enhanced with external tools and services through MCP (Model Conte
 <CodeGroup>
 ```typescript TypeScript (Pass URL)
 const agent = stagehand.agent({
-  provider: "openai",
-  model: "computer-use-preview",
+  provider: "google",
+  model: "gemini-2.5-computer-use-preview-10-2025",
   integrations: [
     `https://mcp.exa.ai/mcp?exaApiKey=${process.env.EXA_API_KEY}`,
   ],
   instructions: `You have access to web search through Exa. Use it to find current information before browsing.`,
   options: {
-    apiKey: process.env.OPENAI_API_KEY,
+    apiKey: process.env.GOOGLE_API_KEY,
   },
 });
 
@@ -99,12 +99,12 @@ const supabaseClient = await connectToMCPServer(
 );
 
 const agent = stagehand.agent({
-  provider: "openai",
-  model: "computer-use-preview",
+  provider: "google",
+  model: "gemini-2.5-computer-use-preview-10-2025",
   integrations: [supabaseClient],
   instructions: `You can interact with Supabase databases. Use these tools to store and retrieve data.`,
   options: {
-    apiKey: process.env.OPENAI_API_KEY,
+    apiKey: process.env.GOOGLE_API_KEY,
   },
 });
 
@@ -117,13 +117,13 @@ MCP integrations enable agents to be more powerful by combining browser automati
 </Tip>
 
 <Warning>
-Stagehand uses a 1024x768 viewport by default (the optimal size for Computer Use Agents). Other viewport sizes may reduce performance. If you need to modify the viewport, you can edit in the [Browser Configuration](/configuration/browser).
+Stagehand uses a 1288x711 viewport by default (the optimal size for Computer Use Agents). Other viewport sizes may reduce performance. If you need to modify the viewport, you can edit in the [Browser Configuration](/configuration/browser).
 </Warning>
 
 
 ## Available Models
 
-Use specialized computer use models (e.g., `computer-use-preview` from OpenAI or `claude-sonnet-4-20250514` from Anthropic)
+Use specialized computer use models (e.g., `gemini-2.5-computer-use-preview-10-2025` from Google or `claude-sonnet-4-20250514` from Anthropic)
 
 <Card title="Available Models" icon="robot" href="/configuration/models">
   Check out the guide on how to use different models with Stagehand.
@@ -291,7 +291,7 @@ if (firstResult.success === true) {
 **Problem**: Agent clicks on wrong elements or fails to interact with the correct UI components
 
 **Solutions**:
-- Ensure proper viewport size: Stagehand uses `1024x768` by default (optimal for Computer Use models)
+- Ensure proper viewport size: Stagehand uses `1288x711` by default (optimal for Computer Use models)
 - Avoid changing viewport dimensions as other sizes may reduce performance
 </Accordion>
 

docs/basics/extract.mdx

@@ -36,6 +36,8 @@ Here is how an `extract` call might look for a single object:
 
 <CodeGroup>
 ```typescript TypeScript
+import { z } from 'zod/v3';
+
 const item = await page.extract({
   instruction: "extract the price of the item",
   schema: z.object({
@@ -45,6 +47,8 @@ const item = await page.extract({
 ```
 
 ```python Python
+from pydantic import BaseModel
+
 class Extraction(BaseModel):
     price: float
 
@@ -66,6 +70,8 @@ Here is how an `extract` call might look for a list of objects.
 
 <CodeGroup>
 ```typescript TypeScript
+import { z } from 'zod/v3';
+
 const apartments = await page.extract({
   instruction:
     "Extract ALL the apartment listings and their details, including address, price, and square feet.",
@@ -84,6 +90,8 @@ console.log("the apartment list is: ", apartments);
 ```
 
 ```python Python
+from pydantic import BaseModel
+
 class Apartment(BaseModel):
     address: str
     price: str
@@ -180,6 +188,8 @@ You can provide additional context to your schema to help the model extract the
 
 <CodeGroup>
 ```typescript TypeScript
+import { z } from 'zod/v3';
+
 const apartments = await page.extract({
  instruction:
    "Extract ALL the apartment listings and their details, including address, price, and square feet.",
@@ -196,6 +206,8 @@ const apartments = await page.extract({
 ```
 
 ```python Python
+from pydantic import BaseModel, Field
+
 class Apartment(BaseModel):
     address: str = Field(..., description="the address of the apartment")
     price: str = Field(..., description="the price of the apartment")
@@ -221,6 +233,8 @@ Here is how an `extract` call might look for extracting a link or URL. This also
 
 <CodeGroup>
 ```typescript TypeScript
+import { z } from 'zod/v3';
+
 const extraction = await page.extract({
   instruction: "extract the link to the 'contact us' page",
   schema: z.object({
@@ -232,6 +246,8 @@ console.log("the link to the contact us page is: ", extraction.link);
 ```
 
 ```python Python
+from pydantic import BaseModel, HttpUrl
+
 class Extraction(BaseModel):
     link: HttpUrl # note the usage of HttpUrl here
 
@@ -414,4 +430,4 @@ for page_num in page_numbers:
   <Card title="Observe" icon="magnifying-glass" href="/basics/observe">
     Analyze pages with observe()
   </Card>
-</CardGroup>
+</CardGroup>

docs/basics/observe.mdx

@@ -109,13 +109,15 @@ const { data } = await page.extract({
 });
 ```
 ```python Python
-# Use observe to validate elements before extraction
-[ table ] = await page.observe("Find the data table")
+# Use observe to find the specific section (table, form, list, etc.)
+tables = await page.observe("Find the data table")
+table = tables[0]  # Get the first suggestion
 
+# Extract data using the selector to minimize context
 extraction = await page.extract(
-  "Extract data from the table",
-  schema=Data, # Pydantic schema
-  selector=table.selector # Reduce context scope needed for extraction
+    "Extract data from the table",
+    schema=TableData,  # Pydantic schema
+    selector=table.selector  # Focus extraction on just this table
 )
 ```
 </CodeGroup>
@@ -216,7 +218,7 @@ except Exception as error:
 - Make sure the element exists on the page
 - Use explicit instructions to find the element
 - Ensure page has fully loaded
-- Look at the [debugging workflows](/best-practices/debugging-workflows) logs, if the element is there then the LLM might be hallucinating/not catching it. 
+- Look at the [debugging workflows](/configuration/logging) logs, if the element is there then the LLM might be hallucinating/not catching it. 
 </Accordion>
 
 <Accordion title="Inaccurate element descriptions">
@@ -225,7 +227,7 @@ except Exception as error:
 **Solutions**:
 - Use more capable models: check [evals](https://stagehand.dev/evals) for the best models for your use case
 - Provide more specific instructions
-- Log inference to file (see [debugging workflows](/best-practices/debugging-workflows)) to get an LLM trace
+- Log inference to file (see [debugging workflows](/configuration/logging)) to get an LLM trace
 
 </Accordion>
 <Accordion title="Wrong method identified">
@@ -255,8 +257,8 @@ Extract structured data from observed elements
 Monitor and debug observation performance  
 </Card>
 
-<Card title="Best Practices" icon="star" href="/best-practices/best-practices">
-Advanced patterns and optimization techniques
+<Card title="Optimizations" icon="star" href="/best-practices/caching">
+Advanced optimization and patterns techniques
 </Card>
 </CardGroup>