page-agent

Page Agent Integration Assistant

Helps you quickly integrate Alibaba Page Agent into Web projects to implement natural language control of web interfaces.

Core Concepts

Page Agent isa JavaScript Agent running inside a web page, not a browser automation tool:

• ✅ Can operate on the DOM of a loaded web page
• ❌ Cannot open new web pages or navigate on its own
• ✅ Supports natural language control of the UI
• ❌ Cannot replace Selenium/Playwright

Quick Integration

Method 1: CDN one-liner (for testing)

<script src="https://cdn.jsdelivr.net/npm/page-agent@1.5.8/dist/iife/page-agent.demo.js" crossorigin="true"></script>

⚠️ Note: Uses the Demo LLM, suitable only for technical evaluation, and you must comply with the terms of use.

Method 2: NPM installation (recommended for production)

npm install page-agent

Basic Configuration

TypeScript/JavaScript

import { PageAgent } from 'page-agent'

const agent = new PageAgent({
  model: 'qwen-max',                    // 或 gpt-4o, claude-3-5-sonnet-20241022 等
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
  apiKey: 'YOUR_API_KEY',
  language: 'zh-CN',                    // 或 'en-US'
})

await agent.execute('点击登录按钮')

Vue 3 Component Example

<template>
  <div>
    <input v-model="userInput" placeholder="输入指令..." @keyup.enter="execute">
    <button @click="execute">执行</button>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { PageAgent } from 'page-agent'

const agent = ref(null)
const userInput = ref('')

onMounted(() => {
  agent.value = new PageAgent({
    model: 'qwen-max',
    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    apiKey: 'YOUR_API_KEY',
    language: 'zh-CN',
  })
})

const execute = async () => {
  await agent.value.execute(userInput.value)
}
</script>

React Component Example

import { useEffect, useState, useRef } from 'react'
import { PageAgent } from 'page-agent'

export function PageAgentComponent() {
  const agentRef = useRef<PageAgent | null>(null)
  const [input, setInput] = useState('')

  useEffect(() => {
    agentRef.current = new PageAgent({
      model: 'gpt-4o',
      baseURL: 'https://api.openai.com/v1',
      apiKey: 'YOUR_API_KEY',
      language: 'en-US',
    })
  }, [])

  const handleExecute = async () => {
    await agentRef.current?.execute(input)
  }

  return (
    <div>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyDown={(e) => e.key === 'Enter' && handleExecute()}
        placeholder="Enter command..."
      />
      <button onClick={handleExecute}>Execute</button>
    </div>
  )
}

LLM Configuration

Alibaba Cloud Tongyi Qianwen

const agent = new PageAgent({
  model: 'qwen-max',                    // qwen-max, qwen-plus, qwen-turbo
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
  apiKey: 'sk-xxx',
  language: 'zh-CN',
})

OpenAI

const agent = new PageAgent({
  model: 'gpt-4o',                      // gpt-4o, gpt-4o-mini, gpt-3.5-turbo
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'sk-xxx',
  language: 'en-US',
})

Claude

const agent = new PageAgent({
  model: 'claude-3-5-sonnet-20241022',
  baseURL: 'https://api.anthropic.com/v1',
  apiKey: 'sk-ant-xxx',
  language: 'en-US',
})

Custom OpenAI-Compatible API

const agent = new PageAgent({
  model: 'your-model-name',
  baseURL: 'https://your-api-endpoint/v1',
  apiKey: 'your-api-key',
  language: 'zh-CN',
})

Common Scenario Implementations

Intelligent Form Filling

// 用户说："帮我填写注册表单，姓名张三，邮箱zhang@example.com"
await agent.execute('填写注册表单：姓名张三，邮箱zhang@example.com')

// 或者分步引导
await agent.execute('找到注册表单的姓名输入框')
await agent.execute('填写张三到姓名输入框')
await agent.execute('填写 zhang@example.com 到邮箱输入框')

Human Confirmation Mechanism

const agent = new PageAgent({
  model: 'gpt-4o',
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'YOUR_API_KEY',
  language: 'en-US',
  onBeforeAction: async (action) => {
    // 在执行操作前请求用户确认
    const confirmed = confirm(`即将执行: ${action.description}\n确认继续？`)
    return confirmed
  },
})

Multilingual Support

// 中文环境
const agentZh = new PageAgent({
  model: 'qwen-max',
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
  apiKey: 'YOUR_API_KEY',
  language: 'zh-CN',                    // 指令使用中文
})

// 英文环境
const agentEn = new PageAgent({
  model: 'gpt-4o',
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'YOUR_API_KEY',
  language: 'en-US',                    // 指令使用英文
})

Error Handling

try {
  await agent.execute('点击提交按钮')
} catch (error) {
  if (error.message.includes('element not found')) {
    console.error('未找到目标元素')
    // 提供更友好的错误提示或备选方案
  } else if (error.message.includes('permission denied')) {
    console.error('操作被拒绝，可能需要权限')
  }
}

Chrome Extension Integration

Cross-page tasks require installing the Chrome extension:

# 安装扩展（从 Page Agent 官方文档获取）
# 在 manifest.json 中配置权限

Extension configuration example:

{
  "manifest_version": 3,
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  }
}

Best Practices

1. API Key Security: Do not hard-code API Keys in the frontend; use environment variables or a backend proxy
2. Human Confirmation: For sensitive operations, always use onBeforeAction to request user confirmation
3. Error Handling: Catch all possible errors and provide a friendly user experience
4. Language Matching: language parameter should be consistent with the user interface language
5. Performance Optimization: Avoid frequently executing complex operations; consider batch processing

Limitations and Notes

Limitation	Description
Cannot open new pages	Can only work within an already loaded web page
Cross-origin restrictions	Subject to browser same-origin policy
DOM dependency	Depends on the web page's DOM structure; structural changes may affect results
LLM cost	Each operation calls the LLM, incurring API fees
Not suitable for automated testing	Not designed for testing frameworks and cannot replace Cypress/Playwright

Reference Resources

• Official Documentation
• Demo
• GitHub Repository
• Chrome Extension Guide

Troubleshooting

Problem: Element not found

• Check whether the element is visible on the page
• Confirm whether the element selector is correct
• Try a more specific description (such as "red submit button" instead of "submit button")

Problem: API call failed

• Verify whether the API Key is correct
• Check the network connection
• Confirm that the LLM service is available

Issue: Operation not responding

• Confirm execute() is awaited
• Check console error messages
• Verify whether the webpage DOM structure is stable