modify template
This commit is contained in:
김경종
@@ -0,0 +1,432 @@
|
||||
## API Reference
|
||||
Use this as the supported `agent.browsers.*` surface.
|
||||
|
||||
```ts
|
||||
// Installed by setupBrowserRuntime({ globals: globalThis }).
|
||||
const browser = await agent.browsers.get("iab");
|
||||
interface Agent {
|
||||
browsers: Browsers; // API for finding and selecting browsers.
|
||||
documentation: Documentation; // API for reading packaged browser-use documentation by name.
|
||||
}
|
||||
|
||||
interface Browsers {
|
||||
get(id: string): Promise<Browser>; // Get a browser by id or client type.
|
||||
list(): Promise<Array<BrowserInfo>>; // List available browsers.
|
||||
}
|
||||
|
||||
interface Browser {
|
||||
browserId: string; // Browser id selected by `agent.browsers.get()`.
|
||||
capabilities: BrowserCapabilityCollection; // Browser-scoped optional capabilities advertised by the connected backend; discover IDs with `await browser.capabilities.list()`, then call `await (await browser.capabilities.get(id)).documentation()` for method details.
|
||||
tabs: Tabs; // API for interacting with browser tabs.
|
||||
user: BrowserUser; // Readonly context about tabs in the user's browser windows.
|
||||
documentation(): Promise<string>; // Read browser guidance and the core API reference.
|
||||
nameSession(name: string): Promise<void>; // Name the current browser automation session.
|
||||
}
|
||||
|
||||
interface BrowserUser {
|
||||
|
||||
openTabs(): Promise<Array<BrowserUserTabInfo>>; // List open top-level tabs across the user's browser windows ordered by `lastOpened` descending.
|
||||
}
|
||||
|
||||
interface Tabs {
|
||||
|
||||
get(id: string): Promise<Tab>; // Get a tab by id.
|
||||
list(): Promise<Array<TabInfo>>; // List open tabs in the browser.
|
||||
new(): Promise<Tab>; // Create and return a new tab in the browser.
|
||||
selected(): Promise<undefined | Tab>; // Return the currently selected tab, if any.
|
||||
}
|
||||
|
||||
interface Tab {
|
||||
capabilities: TabCapabilityCollection; // Tab-scoped optional capabilities advertised by the connected backend; discover IDs with `await tab.capabilities.list()`, then call `await (await tab.capabilities.get(id)).documentation()` for method details.
|
||||
clipboard: TabClipboardAPI; // API for interacting with clipboard content in this tab.
|
||||
|
||||
cua: CUAAPI; // API for interacting with the tab via the cua api
|
||||
dev: TabDevAPI; // API for developer-oriented tab inspection.
|
||||
dom_cua: DomCUAAPI; // API for interacting with the tab via the dom based cua api
|
||||
id: string; // A tab's unique identifier
|
||||
playwright: PlaywrightAPI; // API for interacting with the tab via the playwright api
|
||||
back(): Promise<void>; // Navigate this tab back in history.
|
||||
close(): Promise<void>; // Close this tab.
|
||||
forward(): Promise<void>; // Navigate this tab forward in history.
|
||||
goto(url: string): Promise<void>; // Open a URL in this tab.
|
||||
reload(): Promise<void>; // Reload this tab.
|
||||
screenshot(options: ScreenshotOptions): Promise<Uint8Array>; // Capture a screenshot of this tab.
|
||||
title(): Promise<undefined | string>; // Get the current title for this tab.
|
||||
url(): Promise<undefined | string>; // Get the current URL for this tab.
|
||||
}
|
||||
|
||||
interface CUAAPI {
|
||||
click(options: ClickOptions): Promise<void>; // Click at a coordinate in the current viewport.
|
||||
double_click(options: DoubleClickOptions): Promise<void>; // Double click at a coordinate in the current viewport.
|
||||
|
||||
drag(options: DragOptions): Promise<void>; // Drag from a point to a point by the provided path.
|
||||
keypress(options: KeypressOptions): Promise<void>; // Press control characters at the current focused element (focus it first via click/dblclick).
|
||||
move(options: MoveOptions): Promise<void>; // Move the mouse to a point by the provided x and y coordinates.
|
||||
scroll(options: ScrollOptions): Promise<void>; // Scroll by a delta from a specific viewport coordinate.
|
||||
type(options: TypeOptions): Promise<void>; // Type text at the current focus.
|
||||
}
|
||||
|
||||
interface DomCUAAPI {
|
||||
click(options: DomClickOptions): Promise<void>; // Click a DOM node by its id from the visible DOM snapshot.
|
||||
double_click(options: DomClickOptions): Promise<void>; // Double-click a DOM node by its id.
|
||||
|
||||
get_visible_dom(): Promise<unknown>; // Return a filtered DOM with node ids for interactable elements.
|
||||
keypress(options: DomKeypressOptions): Promise<void>; // Press control characters at the currently focused element (focus it first via click/dblclick).
|
||||
scroll(options: DomScrollOptions): Promise<void>; // Scroll either the page or a specific node (if node_id provided) by deltas.
|
||||
type(options: DomTypeOptions): Promise<void>; // Type text into the currently focused element (focus via click first).
|
||||
}
|
||||
|
||||
interface PlaywrightAPI {
|
||||
domSnapshot(): Promise<string>; // Return a snapshot of the current DOM as a string, including expanded iframe body content when available.
|
||||
|
||||
evaluate<TResult, TArg>(pageFunction: PlaywrightEvaluateFunction<TArg, TResult>, arg?: TArg, options?: PlaywrightEvaluateOptions): Promise<TResult>; // Evaluate JavaScript in a read-only page scope.
|
||||
expectNavigation<T>(action: () => Promise<T>, options: { timeoutMs?: number; url?: string; waitUntil?: LoadState }): Promise<T>; // Expect a navigation triggered by an action.
|
||||
frameLocator(frameSelector: string): PlaywrightFrameLocator; // Create a frame-scoped locator builder.
|
||||
getByLabel(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by label text within the page.
|
||||
getByPlaceholder(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by placeholder text within the page.
|
||||
getByRole(role: string, options: { exact?: boolean; name?: TextMatcher }): PlaywrightLocator; // Find elements by ARIA role within the page.
|
||||
getByTestId(testId: string): PlaywrightLocator; // Find elements by test id within the page.
|
||||
getByText(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by text within the page.
|
||||
locator(selector: string): PlaywrightLocator; // Create a locator scoped to this tab.
|
||||
waitForEvent(event: "download", options?: WaitForEventOptions): Promise<PlaywrightDownload>; // Wait for the next event on the page.
|
||||
|
||||
waitForLoadState(options: PageWaitForLoadStateOptions): Promise<void>; // Wait for the page to reach a specific load state.
|
||||
waitForTimeout(timeoutMs: number): Promise<void>; // Wait for a fixed duration.
|
||||
waitForURL(url: string, options: PageWaitForURLOptions): Promise<void>; // Wait for the page URL to match the provided value.
|
||||
}
|
||||
|
||||
interface PlaywrightFrameLocator {
|
||||
frameLocator(frameSelector: string): PlaywrightFrameLocator; // Create a locator scoped to a nested frame.
|
||||
getByLabel(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by label within this frame.
|
||||
getByPlaceholder(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by placeholder within this frame.
|
||||
getByRole(role: string, options: { exact?: boolean; name?: TextMatcher }): PlaywrightLocator; // Find elements by ARIA role within this frame.
|
||||
getByTestId(testId: string): PlaywrightLocator; // Find elements by test id within this frame.
|
||||
getByText(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by text within this frame.
|
||||
locator(selector: string): PlaywrightLocator; // Create a locator scoped to this frame.
|
||||
}
|
||||
|
||||
interface PlaywrightLocator {
|
||||
all(): Promise<Array<PlaywrightLocator>>; // Resolve to a list of locators for each matched element.
|
||||
allTextContents(options: { timeoutMs?: number }): Promise<Array<string>>; // Return `textContent` for *all* elements matched by this locator.
|
||||
and(locator: PlaywrightLocator): PlaywrightLocator; // Return a locator matching elements that satisfy both this locator and `locator`.
|
||||
check(options: LocatorCheckOptions): Promise<void>; // Check a checkbox or switch-like control.
|
||||
click(options: LocatorClickOptions): Promise<void>; // Click the element matched by this locator.
|
||||
count(): Promise<number>; // Number of elements matching this locator.
|
||||
dblclick(options: LocatorClickOptions): Promise<void>; // Double-click the element matched by this locator.
|
||||
|
||||
fill(value: string, options: { timeoutMs?: number }): Promise<void>; // Replace the element's value with the provided text.
|
||||
filter(options: LocatorFilterOptions): PlaywrightLocator; // Narrow this locator by additional constraints.
|
||||
first(): PlaywrightLocator; // Return a locator pointing at the first matched element.
|
||||
getAttribute(name: string, options: { timeoutMs?: number }): Promise<null | string>; // Return an attribute value from the first matched element.
|
||||
getByLabel(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by label text, scoped to this locator.
|
||||
getByPlaceholder(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by placeholder text, scoped to this locator.
|
||||
getByRole(role: string, options: { exact?: boolean; name?: TextMatcher }): PlaywrightLocator; // Find elements by ARIA role, scoped to this locator.
|
||||
getByTestId(testId: string): PlaywrightLocator; // Find elements by test id, scoped to this locator.
|
||||
getByText(text: TextMatcher, options: { exact?: boolean }): PlaywrightLocator; // Find elements by text content, scoped to this locator.
|
||||
innerText(options: { timeoutMs?: number }): Promise<string>; // Return the rendered (visible) text of the first matched element.
|
||||
isEnabled(): Promise<boolean>; // Whether the first matched element is currently enabled.
|
||||
isVisible(): Promise<boolean>; // Whether the first matched element is currently visible.
|
||||
last(): PlaywrightLocator; // Return a locator pointing at the last matched element.
|
||||
locator(selector: string, options: LocatorLocatorOptions): PlaywrightLocator; // Create a descendant locator scoped to this locator.
|
||||
nth(index: number): PlaywrightLocator; // Return a locator pointing at the Nth matched element.
|
||||
or(locator: PlaywrightLocator): PlaywrightLocator; // Return a locator matching elements that satisfy either this locator or `locator`.
|
||||
press(value: string, options: { timeoutMs?: number }): Promise<void>; // Press a keyboard key while this locator is focused.
|
||||
selectOption(value: SelectOptionInput | Array<SelectOptionInput>, options: { timeoutMs?: number }): Promise<void>; // Select one or more options on a native `<select>` element.
|
||||
setChecked(checked: boolean, options: LocatorCheckOptions): Promise<void>; // Set a checkbox or switch-like control to a checked/unchecked state.
|
||||
textContent(options: { timeoutMs?: number }): Promise<null | string>; // Return the raw textContent of the first matched element (or null if missing).
|
||||
type(value: string, options: { timeoutMs?: number }): Promise<void>; // Type text into the element without clearing existing content.
|
||||
uncheck(options: LocatorCheckOptions): Promise<void>; // Uncheck a checkbox or switch-like control.
|
||||
waitFor(options: LocatorWaitForOptions): Promise<void>; // Wait for the element to reach a specific state.
|
||||
}
|
||||
|
||||
interface PlaywrightDownload {
|
||||
|
||||
}
|
||||
|
||||
interface TabClipboardAPI {
|
||||
read(): Promise<Array<TabClipboardItem>>; // Read clipboard items, including text and binary payloads.
|
||||
readText(): Promise<string>; // Read plain text from the browser clipboard.
|
||||
write(items: Array<TabClipboardItem>): Promise<void>; // Write clipboard items.
|
||||
writeText(text: string): Promise<void>; // Write plain text to the browser clipboard.
|
||||
}
|
||||
|
||||
interface TabDevAPI {
|
||||
logs(options: TabDevLogsOptions): Promise<Array<TabDevLogEntry>>; // Read console log messages captured for this tab.
|
||||
}
|
||||
|
||||
interface Documentation {
|
||||
get(name: string): Promise<string>; // Read packaged documentation by its extensionless relative path.
|
||||
}
|
||||
|
||||
interface BrowserInfo {
|
||||
capabilities: ClientCapabilities;
|
||||
id: string;
|
||||
metadata?: Record<string, string>;
|
||||
name: string;
|
||||
type: ClientType;
|
||||
}
|
||||
|
||||
type BrowserCapabilityCollection = {
|
||||
get(id: string): Promise<unknown>;
|
||||
list(): Promise<Array<{ id: string; description: string }>>;
|
||||
};
|
||||
|
||||
interface BrowserUserTabInfo {
|
||||
id: string; // Opaque identifier for this browser tab.
|
||||
lastOpened?: string; // ISO 8601 timestamp for the last time the tab was opened or focused.
|
||||
tabGroup?: string; // User-visible tab group name when the tab belongs to one.
|
||||
title?: string; // User-visible tab title.
|
||||
url?: string; // Current tab URL.
|
||||
}
|
||||
|
||||
interface TabsContentOptions {
|
||||
|
||||
timeoutMs?: number; // Maximum time to wait for each page load, in milliseconds.
|
||||
urls: Array<string>; // URLs to load in temporary background tabs.
|
||||
}
|
||||
|
||||
interface TabsContentResult {
|
||||
|
||||
title: null | string; // The resolved page title when available.
|
||||
url: string; // The resolved page URL when available, otherwise the requested URL.
|
||||
}
|
||||
|
||||
interface FinalizeTabsOptions {
|
||||
keep?: Array<FinalizeTabsKeep>; // Explicit tab dispositions to preserve after cleanup.
|
||||
}
|
||||
|
||||
interface TabInfo {
|
||||
id: string; // Metadata describing an open tab.
|
||||
title?: string;
|
||||
url?: string;
|
||||
}
|
||||
|
||||
type TabCapabilityCollection = {
|
||||
get(id: string): Promise<unknown>;
|
||||
list(): Promise<Array<{ id: string; description: string }>>;
|
||||
};
|
||||
|
||||
type ScreenshotOptions = {
|
||||
clip?: ClipRect; // Crop to a specific rectangle instead of the full viewport.
|
||||
fullPage?: boolean; // Capture the full page instead of the viewport.
|
||||
};
|
||||
|
||||
type ClickOptions = {
|
||||
button?: number; // Mouse button (1-left, 2-middle/wheel, 3-right, 4-back, 5-forward).
|
||||
keypress?: Array<string>; // Modifier keys held during the click.
|
||||
x: number;
|
||||
y: number;
|
||||
};
|
||||
|
||||
type DoubleClickOptions = {
|
||||
keypress?: Array<string>; // Modifier keys held during the double click.
|
||||
x: number;
|
||||
y: number;
|
||||
};
|
||||
|
||||
type DragOptions = {
|
||||
keys?: Array<string>; // Optional modifier keys held during the drag.
|
||||
path: Array<{ x: number; y: number }>; // Drag path as a list of points.
|
||||
};
|
||||
|
||||
type KeypressOptions = {
|
||||
keys: Array<string>; // Key combination to press.
|
||||
};
|
||||
|
||||
type MoveOptions = {
|
||||
keys?: Array<string>; // Optional modifier keys held while moving.
|
||||
x: number;
|
||||
y: number;
|
||||
};
|
||||
|
||||
type ScrollOptions = {
|
||||
keypress?: Array<string>; // Modifier keys held during scroll.
|
||||
scrollX: number;
|
||||
scrollY: number;
|
||||
x: number;
|
||||
y: number;
|
||||
};
|
||||
|
||||
type TypeOptions = {
|
||||
text: string;
|
||||
};
|
||||
|
||||
type DomClickOptions = {
|
||||
node_id: string; // Node id from `get_visible_dom()`.
|
||||
};
|
||||
|
||||
type DomKeypressOptions = {
|
||||
keys: Array<string>; // Key combination to press.
|
||||
};
|
||||
|
||||
type DomScrollOptions = {
|
||||
node_id?: string; // Optional node id to scroll within.
|
||||
x: number; // Horizontal scroll delta.
|
||||
y: number; // Vertical scroll delta.
|
||||
};
|
||||
|
||||
type DomTypeOptions = {
|
||||
text: string; // Text to type into the currently focused element.
|
||||
};
|
||||
|
||||
type ElementInfoOptions = {
|
||||
includeNonInteractable?: boolean; // When true, include non-interactable elements in addition to interactable targets.
|
||||
x: number;
|
||||
y: number;
|
||||
};
|
||||
|
||||
type ElementInfo = {
|
||||
ariaName?: string | null; // Accessible name if available.
|
||||
boundingBox?: ElementInfoRect | null; // Element bounds in screenshot coordinates.
|
||||
nodeId?: number | null; // Backend node id that can be passed to DOM-inspection APIs when available.
|
||||
preview: string; // Compact human-readable node preview.
|
||||
role?: string | null; // Computed ARIA role if available.
|
||||
selector: ElementInfoSelector; // Suggested selector data for this element.
|
||||
tagName: string; // Lowercased HTML tag name.
|
||||
testId?: string | null; // Configured test id attribute if present.
|
||||
visibleText?: string | null; // Rendered visible text, selected option text, or visible form value when available.
|
||||
};
|
||||
|
||||
type ElementScreenshotOptions = {
|
||||
includeNonInteractable?: boolean; // When true, highlight non-interactable elements in addition to interactable targets.
|
||||
x: number;
|
||||
y: number;
|
||||
};
|
||||
|
||||
type PlaywrightEvaluateFunction<TArg, TResult> = string | (arg: TArg) => TResult | Promise<TResult>;
|
||||
|
||||
type PlaywrightEvaluateOptions = {
|
||||
timeoutMs?: number; // Maximum time to spend setting up the read-only DOM scope and running the script.
|
||||
};
|
||||
|
||||
type LoadState = "load" | "domcontentloaded" | "networkidle";
|
||||
|
||||
type TextMatcher = string | RegExp;
|
||||
|
||||
type WaitForEventOptions = {
|
||||
timeoutMs?: number;
|
||||
};
|
||||
|
||||
type PageWaitForLoadStateOptions = {
|
||||
state?: LoadState;
|
||||
timeoutMs?: number;
|
||||
};
|
||||
|
||||
type PageWaitForURLOptions = {
|
||||
timeoutMs?: number;
|
||||
waitUntil?: WaitUntil;
|
||||
};
|
||||
|
||||
type LocatorCheckOptions = {
|
||||
force?: boolean;
|
||||
timeoutMs?: number;
|
||||
};
|
||||
|
||||
type LocatorClickOptions = {
|
||||
button?: MouseButton;
|
||||
force?: boolean;
|
||||
modifiers?: Array<KeyboardModifier>;
|
||||
timeoutMs?: number;
|
||||
};
|
||||
|
||||
type LocatorFilterOptions = {
|
||||
has?: PlaywrightLocator;
|
||||
hasNot?: PlaywrightLocator;
|
||||
hasNotText?: TextMatcher;
|
||||
hasText?: TextMatcher;
|
||||
visible?: boolean;
|
||||
};
|
||||
|
||||
type LocatorLocatorOptions = {
|
||||
has?: PlaywrightLocator;
|
||||
hasNot?: PlaywrightLocator;
|
||||
hasNotText?: TextMatcher;
|
||||
hasText?: TextMatcher;
|
||||
};
|
||||
|
||||
type SelectOptionInput = string | SelectOptionDescriptor;
|
||||
|
||||
type LocatorWaitForOptions = {
|
||||
state: WaitForState;
|
||||
timeoutMs?: number;
|
||||
};
|
||||
|
||||
type TabClipboardItem = {
|
||||
entries: Array<TabClipboardEntry>;
|
||||
presentationStyle?: "unspecified" | "inline" | "attachment";
|
||||
};
|
||||
|
||||
interface TabDevLogsOptions {
|
||||
filter?: string; // Optional substring filter applied to the rendered log message.
|
||||
levels?: Array<"debug" | "info" | "log" | "warn" | "error" | "warning">; // Optional levels to include.
|
||||
limit?: number; // Maximum number of logs to return.
|
||||
}
|
||||
|
||||
interface TabDevLogEntry {
|
||||
level: "debug" | "info" | "log" | "warn" | "error"; // Console log level.
|
||||
message: string; // Rendered log message text.
|
||||
timestamp: string; // ISO 8601 timestamp for when the runtime captured the log.
|
||||
url?: string; // Source URL reported by the browser runtime, when available.
|
||||
}
|
||||
|
||||
interface ClientCapabilities {
|
||||
browser?: Array<CapabilityInfo>;
|
||||
tab?: Array<CapabilityInfo>;
|
||||
}
|
||||
|
||||
type ClientType = "iab" | "extension" | "cdp";
|
||||
|
||||
type TabsContentType = "html" | "text" | "domSnapshot";
|
||||
|
||||
interface FinalizeTabsKeep {
|
||||
status: FinalizeTabStatus; // Where the kept tab belongs after cleanup.
|
||||
tab: string | Tab | TabInfo; // Tab object to keep open after browser cleanup.
|
||||
}
|
||||
|
||||
type ClipRect = {
|
||||
height: number;
|
||||
width: number;
|
||||
x: number;
|
||||
y: number;
|
||||
};
|
||||
|
||||
type ElementInfoRect = {
|
||||
height: number;
|
||||
width: number;
|
||||
x: number;
|
||||
y: number;
|
||||
};
|
||||
|
||||
type ElementInfoSelector = {
|
||||
candidates: Array<string>; // Ranked selector candidates for the element.
|
||||
frameSelectors?: Array<string>; // Frame selectors to enter before using the element selector.
|
||||
primary?: string | null; // The preferred selector for the element when available.
|
||||
};
|
||||
|
||||
type WaitUntil = LoadState | "commit";
|
||||
|
||||
type MouseButton = "left" | "right" | "middle";
|
||||
|
||||
type KeyboardModifier = "Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift";
|
||||
|
||||
type SelectOptionDescriptor = {
|
||||
index?: number;
|
||||
label?: string;
|
||||
value?: string;
|
||||
};
|
||||
|
||||
type WaitForState = "attached" | "detached" | "visible" | "hidden";
|
||||
|
||||
type TabClipboardEntry = {
|
||||
base64?: string;
|
||||
mimeType: string;
|
||||
text?: string;
|
||||
};
|
||||
|
||||
interface CapabilityInfo {
|
||||
description: string;
|
||||
id: string;
|
||||
}
|
||||
|
||||
type FinalizeTabStatus = "handoff" | "deliverable";
|
||||
```
|
||||
Reference in New Issue
Block a user