Quickstart (TypeScript)

1
import * as dotenv from "dotenv";
2
import { Agent, run, tool } from "@openai/agents";
3
import { chromium, type Browser, type Page } from "playwright";
4
import Steel from "steel-sdk";
5
import { z } from "zod";
6

7
dotenv.config();
8

9
const STEEL_API_KEY = process.env.STEEL_API_KEY!;
10
const steel = new Steel({ steelAPIKey: STEEL_API_KEY });
11

12
let session: Awaited<ReturnType<typeof steel.sessions.create>> | null = null;
13
let browser: Browser | null = null;
14
let page: Page | null = null;
15

16
const openSession = tool({
17
  name: "open_session",
18
  description:
19
    "Open a Steel cloud browser session. Call exactly once, before anything else.",
20
  parameters: z.object({}),
21
  execute: async () => {
22
    session = await steel.sessions.create({});
23
    browser = await chromium.connectOverCDP(
24
      `${session.websocketUrl}&apiKey=${STEEL_API_KEY}`
25
    );
26
    const ctx = browser.contexts()[0];
27
    page = ctx.pages()[0] ?? (await ctx.newPage());
28
    return { sessionId: session.id, liveViewUrl: session.sessionViewerUrl };
29
  },
30
});
31

32
const navigate = tool({
33
  name: "navigate",
34
  description: "Navigate the open session to a URL and wait for it to load.",
35
  // OpenAI strict JSON Schema rejects "uri" format, so use plain z.string() here.
36
  parameters: z.object({ url: z.string() }),
37
  execute: async ({ url }) => {
38
    if (!page) throw new Error("open_session first.");
39
    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 45_000 });
40
    return { url: page.url(), title: await page.title() };
41
  },
42
});
43

44
const snapshot = tool({
45
  name: "snapshot",
46
  description:
47
    "Return a readable snapshot of the current page: title, URL, visible text (capped), and a list of links. Call BEFORE extract so you never have to guess CSS selectors.",
48
  parameters: z.object({
49
    maxChars: z.number().int().positive().max(10_000).default(4_000),
50
    maxLinks: z.number().int().positive().max(200).default(50),
51
  }),
52
  execute: async ({ maxChars, maxLinks }) => {
53
    if (!page) throw new Error("open_session first.");
54
    return (await page.evaluate(
55
      ({ maxChars, maxLinks }: { maxChars: number; maxLinks: number }) => {
56
        const text = (document.body.innerText || "").slice(0, maxChars);
57
        const links = Array.from(document.querySelectorAll("a[href]"))
58
          .slice(0, maxLinks)
59
          .map((a) => {
60
            const anchor = a as HTMLAnchorElement;
61
            const t = (anchor.innerText || anchor.textContent || "").trim().slice(0, 120);
62
            return { text: t, href: anchor.href };
63
          })
64
          .filter((l) => l.text && l.href);
65
        return { url: location.href, title: document.title, text, links };
66
      },
67
      { maxChars, maxLinks }
68
    )) as { url: string; title: string; text: string; links: { text: string; href: string }[] };
69
  },
70
});
71

72
const extract = tool({
73
  name: "extract",
74
  description:
75
    "Extract structured rows from the current page using CSS selectors. Prefer calling snapshot() first.",
76
  parameters: z.object({
77
    rowSelector: z.string(),
78
    fields: z.array(z.object({
79
      name: z.string(),
80
      selector: z.string(),
81
      attr: z.string().nullable(),
82
    })).min(1).max(10),
83
    limit: z.number().int().positive().max(20).default(10),
84
  }),
85
  execute: async ({ rowSelector, fields, limit }) => {
86
    if (!page) throw new Error("open_session first.");
87
    const items = (await page.evaluate(
88
      ({ rowSelector, fields, limit }: {
89
        rowSelector: string;
90
        fields: { name: string; selector: string; attr: string | null }[];
91
        limit: number;
92
      }) => {
93
        const rows = Array.from(document.querySelectorAll(rowSelector)).slice(0, limit);
94
        return rows.map((row) => {
95
          const item: Record<string, string> = {};
96
          for (const f of fields) {
97
            const el = f.selector ? (row.querySelector(f.selector) as Element | null) : row;
98
            if (!el) { item[f.name] = ""; continue; }
99
            item[f.name] = f.attr
100
              ? (el.getAttribute(f.attr) ?? "").trim()
101
              : (((el as HTMLElement).innerText ?? el.textContent ?? "")).trim();
102
          }
103
          return item;
104
        });
105
      },
106
      { rowSelector, fields, limit }
107
    )) as Record<string, string>[];
108
    return { count: items.length, items };
109
  },
110
});