.png)
Core methods
Functions for creating, running, and managing tasks, interacting with agents, and handling authentication.| Method / Function | Definition / Purpose |
|---|---|
WebAgent.init(options) | Initialize a WebAgent instance with optional Portal-H authentication. Checks existing tokens and triggers authCallback if login is required. |
WebAgent.withPortalAuth() | Shortcut factory method to initialize a WebAgent using Portal-H popup authentication. |
WebAgent.fromApiKey(apiKey, options) | Initialize a WebAgent using a static API key instead of JWT/Portal-H login. |
agent.run(objective, options) | Execute a web automation task immediately. Returns an AgentTask. |
agent.runStepByStep(objective, options) | Start a task in paused “step-by-step” mode, allowing manual progression of the task. |
agent.runAndWait(objective, options) | Run a task and automatically wait for its completion before returning. |
agent.sendUserInput(taskId, input) | Send human-in-the-loop input to a running task (string or UserInput). |
agent.createTask(request) | Create a task programmatically using a StartTrajectory object. |
agent.getTask(id, requiresAuth?) | Retrieve an existing task by ID. Optionally requires authentication. |
agent.listTasks(query?) | List existing tasks with optional filtering/pagination. Returns a Page<AgentTask>. |
agent.getObjectives() | Get all unique task objectives for the user (useful for filtering). |
agent.listAgents() | Retrieve all available agents from the platform. |
agent.getBestAgent(taskType?) | Return the best agent for a specific task type (web or general). |
agent.submitFeedback(feedback) | Submit feedback about the platform. Returns a FeedbackResponse. |
agent.healthCheck() | Test connectivity and API key validity. Returns true if healthy. |
agent.searchWeb(data, site?) | Quick web search task; can accept a string query or WebSearchData object. |
agent.shopFor(data, site?) | Quick e-commerce task; string input or ShoppingData object. |
agent.fillForm(data, url?) | Quick form-filling task; string URL or FormFillData object. |
agent.extractData(data, description?) | Quick data extraction task; string URL or DataExtractionData object. |
agent.runBatch(tasks) | Run multiple tasks in parallel. Accepts an array of { objective, startUrl, agentIdentifier }. |
agent.waitForAllComplete(tasks, timeoutMs?) | Wait for multiple tasks to finish. Returns the completed tasks. |
Getters
Read-only properties that provide convenient access to task metadata, status, and runtime information.| Method / Property | Definition / Purpose |
|---|---|
id | Read-only. Returns the unique trajectory ID. |
status | Read-only. Current trajectory status (running, paused, completed, etc.). |
objective | Read-only. The task’s objective or instruction. |
isRunning | Read-only. Returns true if the trajectory is currently running. |
isCompleted | Read-only. Returns true if the trajectory has finished (completed, failed, timed out, or interrupted). |
events | Read-only. Array of all trajectory events. |
liveViewUrl | Read-only. URL to view the live trajectory (if available). |
error | Read-only. Any error associated with the trajectory. |
isPublic | Read-only. Returns true if the trajectory is shared publicly. |
createdAt | Read-only. Creation timestamp of the trajectory. |
startedAt | Read-only. Timestamp when the trajectory started. |
finishedAt | Read-only. Timestamp when the trajectory finished. |
duration | Read-only. Duration of the trajectory in milliseconds (from start to finish or current time if running). |
Event handling
Methods for subscribing to trajectory events, status updates, errors, and specific event types like chat messages or web actions.| Method | Definition / Purpose |
|---|---|
onEvent(handler) | Register a callback for any trajectory event. Returns an unsubscribe function. |
onUpdate(handler) | Convenience method for onEvent (generic event updates). |
onStatusChange(handler) | Register a callback for trajectory status changes. Returns an unsubscribe function. |
onError(handler) | Register a callback for errors during trajectory execution. |
onChatMessage(handler) | Register a callback specifically for chat message events. |
onWebAction(handler) | Register a callback specifically for web action events. |
Polling
Functions that automatically fetch real-time updates from the platform, keeping your task state in sync.| Method | Definition / Purpose |
|---|---|
startPolling(intervalMs) | Begin polling the server for trajectory updates. Default interval is 2000ms. |
stopPolling() | Stop polling for updates. |
pollForUpdates() | Poll the server once for updates; triggers events, status changes, and errors. |
Task control
Methods to pause, resume, stop, or otherwise control a task while it’s running.| Method | Definition / Purpose |
|---|---|
refresh() | Refresh trajectory data from the server and update status/events. |
pause() | Pause the trajectory. Returns true if successful. |
resume() | Resume a paused trajectory. Returns true if successful. |
stop() | Stop/interrupt the trajectory. Returns true if successful. |
sendUserInput(input) | Send human-in-the-loop input to the task (string or UserInput). Returns true if successful. |
stepForward() | Step forward one action in step-by-step mode (resumes a paused trajectory). |
makePublic() | Make the trajectory publicly viewable. |
makePrivate() | Make the trajectory private again. |
Promise-based waiting
Functions that let you wait asynchronously for a task to complete or for specific events to occur.| Method | Definition / Purpose |
|---|---|
waitForCompletion(timeoutMs) | Waits for trajectory to finish. Resolves with trajectory data or rejects on timeout/failure. |
waitForEvent(eventType, timeoutMs) | Waits for a specific event type to occur. Resolves with the event or rejects on timeout. |
Cleanup
Methods to stop polling and remove all event handlers, freeing resources when a task is no longer needed.| Method | Definition / Purpose |
|---|---|
destroy() | Stop polling and remove all event handlers to free resources. |
Helper methods for event filtering
Utility functions to extract specific event types or retrieve details like the last web action or screenshots.| Method | Definition / Purpose |
|---|---|
getChatMessages() | Returns all ChatMessageEvent events. |
getWebActions() | Returns all WebActionEvent events. |
getLastWebAction() | Returns the last web action performed (most recent WebActionEvent). |
getLastScreenshots() | Returns pre/post-action screenshots from the last web action, if available. |