PageAgent
The GUI Agent Living in Your Webpage. Control web interfaces with natural language through direct DOM interaction.
A Practical Approach to Web Automation
PageAgent is a technical solution designed for developers who need to add agentic capabilities to their web applications. Instead of relying on external tools or complex server-side scripts, this system runs directly within the browser session. It acts as an intelligent operator that understands the structure of the page and can perform actions based on simple text instructions.
The development of this tool was driven by the need for more integrated and secure web agents. Many existing solutions require access to the entire desktop or use screenshots to understand what is happening on the screen. PageAgent takes a different path by interacting with the Document Object Model directly. This ensures that the agent sees the page exactly as the browser does, leading to higher precision and faster execution speeds.
Why Embedded Agents?
- 1
No external software or plugins required for the end user.
- 2
Runs within the security context of the existing web application.
- 3
Direct access to the application state and DOM elements.
- 4
Easy deployment through standard package managers or CDNs.
System Capabilities
Smart DOM Analysis
The system employs a specific method of data dehydration. It removes redundant information from the DOM and presents a clean, text-based map to the intelligence model. This avoids the high resource cost of graphical processing and focuses on the actual structure of the code.
Secure Operation
Control is a vital part of the design. You can define exactly what the agent is allowed to do through operation allowlists. Sensitive information can be protected using built-in data masking, ensuring that the AI only sees what is necessary for the task at hand.
Zero Backend Required
The entire logic is contained within the client-side environment. This means there is no need to write new server-side code or manage complex state on the backend. It integrates with your existing UI and interacts with the page elements naturally.
Bring Your Own Model
The tool is model-agnostic. You can connect it to any large language model that provides a standard API. This gives you the flexibility to choose the best model for your specific budget and performance requirements.
Human-in-the-Loop
The interface includes a side panel that allows users to see what the agent is doing in real-time. If the agent needs help or makes a mistake, the user can intervene quickly. This creates a helpful partnership between the user and the software.
Optional Expansion
While the base tool works effectively on a single page, there is an optional extension available for tasks that require navigating between multiple tabs or browser windows. This expands the scope of the operator when needed.
Technical Implementation Details
The Logic of Text-Based Interaction
Traditional web agents often rely on computer vision to understand a page. This involves taking frequent screenshots and using neural networks to identify objects. While the results can be natural, the process is slow and prone to errors when the page layout changes even slightly. PageAgent avoids these issues by working directly with the code that defines the page.
When the user provides an instruction, the agent scans the Document Object Model. It identifies every interactive element, such as buttons, links, and input fields. Each element is assigned an identifier and a description based on its role in the HTML. This metadata is then used to build a structured representation of the current state. If a button is labeled "Submit" but its internal code says "btn-05," the agent understands both contexts.
Efficiency Through Dehydration
A modern webpage can have thousands of elements, most of which are not relevant for a specific task. Sending the entire HTML to a language model would be expensive and slow. PageAgent uses a technique called DOM dehydration. This process strips away styling information, redundant containers, and hidden elements.
The result is a highly condensed version of the page that contains only what is necessary for logic and action. This reduction in data size makes the system much faster than image-based alternatives. It also helps the intelligence model stay focused on the user's intent without being distracted by complex layouts or animations.
Security and Permission Logic
Because PageAgent runs in the browser, it is bound by the same security policies as any other JavaScript on the site. However, the tool adds an additional layer of control for developers. You can specify a list of allowed actions, such as "clicking" or "reading text." If the agent tries to perform an action that is not on the list, the system will block it.
Furthermore, developers can provide a knowledge base to the agent. This allows the AI to understand the logic of the business without needing access to the backend database. You can define rules like "Always ask for confirmation before submitting an order" or "Do not show pricing for guest users." These rules are enforced at the client level, providing a predictable and safe environment.
Primary Use Cases
Helping businesses and developers achieve more with existing web interfaces.
SaaS Product Copilot
For complex software platforms, finding the right setting or generating a specific report can be difficult for new users. By embedding PageAgent, you can offer a direct interface for help. A user can simply type, "Change my account theme to dark mode," and the agent will find the settings page and update the preference. This reduces the need for extensive tutorials and improves the initial experience.
This approach is particularly effective because it requires no changes to your existing backend logic. The agent interacts with the UI just like a human would, which means your existing security and validation rules remain in place. It is a simple way to add advanced functionality without a large engineering investment.
Modernizing Legacy Systems
Enterprise systems that were built years ago often have outdated and difficult user interfaces. Replacing these systems is a massive and risky project. PageAgent provides an alternative by acting as a modern interface layer. You can give these old applications a voice or a text-command bar.
Users can perform complex workflows through natural language. For example, in an old ERP system, submitting an expense report might take twenty clicks. With the agent, the user can say, "Submit a travel expense for $50 for lunch yesterday," and the operator will handle the navigation and data entry. This improves productivity and reduces frustration without needing to rewrite the core software.
> Scanning legacy DOM...
> Identifying table rows...
> Inputting expense data...
> Success.
Advanced Accessibility
Web accessibility is often treated as an afterthought, leading to barriers for users with impairments. PageAgent changes this by providing a flexible way to interact with any site. It can connect with screen readers or voice-to-text tools to provide a natural language experience.
Individuals who find it hard to use a mouse can control the entire page through their voice. By understanding the intent of the user, the agent can navigate complex layouts and complete actions that might otherwise be impossible. This helps in building software that is truly open to everyone, regardless of their physical abilities.
Integration Steps
NPM Package (Recommended)
Install the package to use in your TypeScript or JavaScript projects.
import { PageAgent } from 'page-agent'
const agent = new PageAgent({
model: 'qwen-max',
apiKey: 'YOUR_KEY',
language: 'en-US',
})
await agent.execute('Fill the name ')
Direct CDN Loading
Excellent for testing or simple HTML pages without a build system.
Technical Notice
The demo CDN uses a shared testing environment. For production use, we strongly suggest using the NPM package and hosting your own model endpoint to ensure privacy and reliability.
Comparing Technical Approaches
| Aspect | PageAgent | Browser-use |
|---|---|---|
| Primary Focus | Embedded within your specific product. | External tool for the whole browser. |
| User Experience | Natural part of the website UI. | Operates from an external window. |
| Security Model | Restricted to the page where it is included. | Has access to all open browser tabs. |
| Developer Goal | Improve your product for the users. | Automate general web scraping tasks. |
Choosing the right tool depends on whether you are building a product feature or an internal automation script.
Privacy and Reliability
When working with AI operators, security cannot be ignored. PageAgent handles data with a focus on local processing. By default, the system interacts with the DOM and sends only the minimal required text to the language model. This is different from systems that record your screen and send video data to a server.
Data Masking
Automatically hide sensitive fields like passwords or credit card numbers from the AI model.
Operation Rules
Set boundaries for what the agent can modify, ensuring that critical data is never changed without approval.
We suggest developers always use their own proxy servers and API endpoints when deploying for actual users. This ensures that you have full control over the communication between the agent and the intelligence model. The MIT license allows you to adapt the code to meet your specific compliance and regulatory requirements.
Technical FAQ
Start Building Your AI Operator
Explore the source code on GitHub and learn how to integrate PageAgent into your project today.
Access the Code on GitHubReleased under the MIT License. Built with TypeScript for the modern web.
Join the discussion on GitHub and help shape the future of in-page agents.