HandstagesAgentToolHandlers interface reference

import type { HandstagesAgentContext } from "@handstage/agent"

interface HandstagesAgentContext {
  pages(): Page[]
  activePage(): Page | undefined
  setActivePage(page: Page): void
  newPage(url?: string): Promise<Page>
}

import type { HandstagesAgent } from "@handstage/agent"

import type { HandstagesAgentToolHandlers } from "@handstage/agent"

import type {
  HandstagesAgent,
  HandstagesAgentContext,
  HandstagesAgentToolHandlers,
} from "@handstage/agent"
import type { Page } from "@handstage/core"

class MyBrowserHandlers implements HandstagesAgentToolHandlers {
  constructor(private ctx: HandstagesAgentContext) {}

  async pages(_input: HandstagesAgent.PagesInput): Promise<HandstagesAgent.PagesOutput> {
    return {
      pages: this.ctx.pages().map((p) => ({
        pageId: p.targetId,
        url: p.url(),
        title: p.title(),
        activated: p === this.ctx.activePage(),
      })),
    }
  }

  async newPage(input: HandstagesAgent.NewPageInput): Promise<HandstagesAgent.NewPageOutput> {
    const page = await this.ctx.newPage(input.url)
    return { pageId: page.targetId }
  }

  async setActivePage(
    input: HandstagesAgent.SetActivePageInput,
  ): Promise<HandstagesAgent.SetActivePageOutput> {
    const page = this.ctx.pages().find((p) => p.targetId === input.pageId)
    if (!page) return { ok: false, error: `No page with id ${input.pageId}` }
    this.ctx.setActivePage(page)
    return { ok: true }
  }

  async goto(input: HandstagesAgent.GotoInput): Promise<HandstagesAgent.GotoOutput> {
    const page = this.getPage(input.pageId)
    if (!page) return { ok: false, error: `No page with id ${input.pageId}` }
    try {
      await page.goto(input.url, {
        waitUntil: input.waitUntil,
        timeout: input.timeoutMs,
      })
      return { ok: true, url: page.url() }
    } catch (err) {
      return { ok: false, error: String(err) }
    }
  }

  // ... implement remaining 13 methods following the same pattern

  private getPage(pageId: string): Page | undefined {
    return this.ctx.pages().find((p) => p.targetId === pageId)
  }
}

import { generateText, tool } from "ai"
import { openai } from "@ai-sdk/openai"
import { V3 } from "@handstage/core"
import {
  handstagesAgentTools,
  type HandstagesAgent,
  type HandstagesAgentContext,
  type HandstagesAgentToolHandlers,
} from "@handstage/agent"

// Step 1 — connect to a local Chrome instance
const browser = await V3.connectLocal()
const ctx: HandstagesAgentContext = browser.context

// Step 2 — implement HandstagesAgentToolHandlers
class BrowserHandlers implements HandstagesAgentToolHandlers {
  constructor(private ctx: HandstagesAgentContext) {}

  async pages(_: HandstagesAgent.PagesInput): Promise<HandstagesAgent.PagesOutput> {
    return {
      pages: this.ctx.pages().map((p) => ({
        pageId: p.targetId,
        url: p.url(),
        title: p.title(),
        activated: p === this.ctx.activePage(),
      })),
    }
  }

  async newPage(input: HandstagesAgent.NewPageInput): Promise<HandstagesAgent.NewPageOutput> {
    const page = await this.ctx.newPage(input.url)
    return { pageId: page.targetId }
  }

  async goto(input: HandstagesAgent.GotoInput): Promise<HandstagesAgent.GotoOutput> {
    const page = this.ctx.pages().find((p) => p.targetId === input.pageId)
    if (!page) return { ok: false, error: "Page not found" }
    try {
      await page.goto(input.url, { waitUntil: input.waitUntil, timeout: input.timeoutMs })
      return { ok: true, url: page.url() }
    } catch (err) {
      return { ok: false, error: String(err) }
    }
  }

  async snapshot(input: HandstagesAgent.SnapshotInput): Promise<HandstagesAgent.SnapshotOutput> {
    const page = this.ctx.pages().find((p) => p.targetId === input.pageId)
    if (!page) return { ok: false, error: "Page not found" }
    try {
      const result = await page.snapshot({ includeIframes: input.includeIframes })
      return { ok: true, tree: result.tree, xpathMap: result.xpathMap, urlMap: result.urlMap }
    } catch (err) {
      return { ok: false, error: String(err) }
    }
  }

  // ... implement remaining methods
}

const handlers = new BrowserHandlers(ctx)

// Step 3 — attach execute functions to each tool
const executableTools = {
  ...handstagesAgentTools,
  pages: tool({ ...handstagesAgentTools.pages, execute: (i) => handlers.pages(i) }),
  newPage: tool({ ...handstagesAgentTools.newPage, execute: (i) => handlers.newPage(i) }),
  goto: tool({ ...handstagesAgentTools.goto, execute: (i) => handlers.goto(i) }),
  snapshot: tool({ ...handstagesAgentTools.snapshot, execute: (i) => handlers.snapshot(i) }),
  // ... attach remaining tools
}

// Step 4 — run the automation task
const result = await generateText({
  model: openai("gpt-4o"),
  tools: executableTools,
  maxSteps: 30,
  system: "You are a browser automation agent. Use the provided tools to complete tasks.",
  prompt: "Open https://example.com, read the page title, and return it.",
})

console.log(result.text)

await browser.close()