### Initialize Page Agent Configuration

Source: https://alibaba.github.io/page-agent/docs/introduction/quick-start

Configure the PageAgent instance with essential parameters such as the LLM model, API base URL, your API key, and the desired language for interactions. Replace 'YOUR_API_KEY' with your actual Aliyun API key.

```javascript
const agent = new PageAgent({
  model: 'qwen3.5-plus',
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
  apiKey: 'YOUR_API_KEY',
  language: 'en-US'
})
```

--------------------------------

### Install Page Agent via CDN (Demo)

Source: https://alibaba.github.io/page-agent/docs/introduction/quick-start

Include the page-agent demo script directly in your HTML using a CDN. This is suitable for quick testing but uses a free, rate-limited testing LLM API. Ensure you agree to the Terms of Use.

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

--------------------------------

### Execute Instructions with Page Agent

Source: https://alibaba.github.io/page-agent/docs/introduction/quick-start

Programmatically execute natural language instructions using the PageAgent instance. This allows for automated interaction with web pages based on text commands. Alternatively, you can display a panel for user input.

```javascript
// Execute natural language instructions programmatically
await agent.execute('Click submit button, then fill username as John');

// Or:
// Show panel for user to input instructions
agent.panel.show()
```

--------------------------------

### Install Page Agent via NPM

Source: https://alibaba.github.io/page-agent/docs/introduction/quick-start

Install the page-agent package using NPM for recommended project integration. This allows you to import and use the PageAgent class within your JavaScript modules.

```javascript
npm install page-agent
import { PageAgent } from 'page-agent'
```

--------------------------------

### Start Ollama with Recommended Environment Variables (Shell)

Source: https://alibaba.github.io/page-agent/docs/features/models

Instructions for starting the Ollama server with environment variables that enhance its capabilities for Page Agent integration. This includes increasing the context length, allowing cross-origin requests, and listening on all network interfaces.

```shell
# macOS / Linux
OLLAMA_CONTEXT_LENGTH=64000 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_ORIGINS="*" ollama serve
```

```powershell
# Windows (PowerShell)
$env:OLLAMA_CONTEXT_LENGTH=64000; $env:OLLAMA_HOST="0.0.0.0:11434"; $env:OLLAMA_ORIGINS="*"; ollama serve
```

--------------------------------

### Assemble PageAgent with Custom UI

Source: https://alibaba.github.io/page-agent/docs/advanced/custom-ui

Demonstrates how to initialize the PageAgentCore with a PageController and mount a custom React UI component. It also shows how to handle user input and trigger task execution.

```typescript
import { PageAgentCore } from '@page-agent/core';
import { PageController } from '@page-agent/page-controller';

const pageController = new PageController({ enableMask: true });

const agent = new PageAgentCore({
  pageController,
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'your-api-key',
  model: 'gpt-5.2',
});

const root = createRoot(document.getElementById('my-ui')!);
root.render(<MyAgentUI agent={agent} />);

agent.onAskUser = async (question) => window.prompt(question) || '';

await agent.execute('Fill the form with test data');

agent.dispose();
```

--------------------------------

### Configure Dynamic Page Instructions for Page Agent

Source: https://alibaba.github.io/page-agent/docs/features/custom-instructions

Defines a callback function to generate page-specific instructions based on the current URL. This example provides tailored guidance for checkout and product listing pages.

```javascript
const agent = new PageAgent({
  // ...other config
  instructions: {
    system: 'You are an order management assistant.',
    getPageInstructions: (url) => {
      if (url.includes('/checkout')) {
        return ` This is the checkout page. - Verify shipping address before proceeding - Check if any discounts are applied - Confirm the total amount with the user `
      }
      if (url.includes('/products')) {
        return ` This is the product listing page. - Use filters to narrow down search results - Check stock availability before adding to cart `
      }
      return undefined // No special instructions for other pages
    }
  }
})
```

--------------------------------

### Define Custom Tools with Zod Schema

Source: https://alibaba.github.io/page-agent/docs/features/custom-tools

Demonstrates how to define custom tools using the tool() helper and Zod for input validation. It includes examples for adding items to a cart and searching a knowledge base.

```typescript
import { z } from 'zod/v4';
import { PageAgent, tool } from 'page-agent';

const pageAgent = new PageAgent({
  customTools: {
    add_to_cart: tool({
      description: 'Add a product to the shopping cart by its product ID.',
      inputSchema: z.object({
        productId: z.string(),
        quantity: z.number().min(1).default(1),
      }),
      execute: async function (input) {
        await fetch('/api/cart', {
          method: 'POST',
          body: JSON.stringify(input),
        });
        return `Added ${input.quantity}x ${input.productId} to cart.`;
      },
    }),
    search_knowledge_base: tool({
      description: 'Search the internal knowledge base and return relevant articles.',
      inputSchema: z.object({
        query: z.string(),
        limit: z.number().max(10).default(3),
      }),
      execute: async function (input) {
        const res = await fetch(
          `/api/kb?q=${encodeURIComponent(input.query)}&limit=${input.limit}`
        );
        const articles = await res.json();
        return JSON.stringify(articles);
      },
    }),
  },
});
```

--------------------------------

### Configure System Instructions for Page Agent

Source: https://alibaba.github.io/page-agent/docs/features/custom-instructions

Sets global directives for the AI's role and behavior across all tasks. This example defines an e-commerce assistant with specific guidelines for order processing and error handling.

```javascript
const agent = new PageAgent({
  // ...other config
  instructions: {
    system: ` You are a professional e-commerce assistant.  Guidelines: - Always confirm before submitting orders - Double-check prices and quantities - Report errors immediately instead of retrying blindly `
  }
})
```

--------------------------------

### Configure Page Agent with OpenAI-Compatible Services (JavaScript)

Source: https://alibaba.github.io/page-agent/docs/features/models

Demonstrates how to initialize PageAgent for OpenAI-compatible services, such as Alibaba Bailian. Requires specifying the baseURL, apiKey, and the desired model. This setup is suitable for cloud-based or private deployments adhering to the OpenAI API.

```javascript
const pageAgent = new PageAgent({
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
  apiKey: 'your-api-key',
  model: 'qwen3.5-plus'
});
```

--------------------------------

### Implement React Hook for PageAgent Events

Source: https://alibaba.github.io/page-agent/docs/advanced/custom-ui

A custom React hook that subscribes to PageAgentCore events. It synchronizes agent status, history, and activity with local component state.

```typescript
function useAgent(agent: PageAgentCore) {
  const [status, setStatus] = useState(agent.status);
  const [history, setHistory] = useState(agent.history);
  const [activity, setActivity] = useState<AgentActivity | null>(null);

  useEffect(() => {
    const onStatus = () => setStatus(agent.status);
    const onHistory = () => setHistory([...agent.history]);
    const onActivity = (e: Event) => setActivity((e as CustomEvent).detail);

    agent.addEventListener('statuschange', onStatus);
    agent.addEventListener('historychange', onHistory);
    agent.addEventListener('activity', onActivity);

    return () => {
      agent.removeEventListener('statuschange', onStatus);
      agent.removeEventListener('historychange', onHistory);
      agent.removeEventListener('activity', onActivity);
    };
  }, [agent]);

  return { status, history, activity };
}
```

--------------------------------

### Ollama Free Testing API Configuration (Shell)

Source: https://alibaba.github.io/page-agent/docs/features/models

Configuration details for accessing Ollama models via a free testing endpoint. This setup is useful for testing local LLM integrations, specifying the Ollama base URL, API key (usually 'NA'), and the model name.

```shell
LLM_BASE_URL="http://localhost:11434/v1"
LLM_API_KEY="NA"
LLM_MODEL_NAME="qwen3:14b"
```

--------------------------------

### Define HistoricalEvent and AgentActivity Types

Source: https://alibaba.github.io/page-agent/docs/advanced/custom-ui

TypeScript type definitions for the event structures used within the PageAgent system. These types define the schema for historical agent memory and real-time activity feedback.

```typescript
type HistoricalEvent = 
  | { type: 'step'; stepIndex: number; reflection: AgentReflection; action: Action } 
  | { type: 'observation'; content: string } 
  | { type: 'user_takeover' } 
  | { type: 'retry'; message: string; attempt: number; maxAttempts: number } 
  | { type: 'error'; message: string };

type AgentActivity = 
  | { type: 'thinking' } 
  | { type: 'executing'; tool: string; input: unknown } 
  | { type: 'executed'; tool: string; input: unknown; output: string; duration: number } 
  | { type: 'retrying'; attempt: number; maxAttempts: number } 
  | { type: 'error'; message: string };
```

--------------------------------

### Masking Sensitive Data with Page Agent (JavaScript)

Source: https://alibaba.github.io/page-agent/docs/features/data-masking

Demonstrates how to use the `transformPageContent` hook to mask common sensitive data patterns within page content. This example uses regular expressions to replace phone numbers, email addresses, China ID card numbers, and bank card numbers with asterisks. The function is asynchronous and returns the modified content.

```javascript
const agent = new PageAgent({
  transformPageContent: async (content) => {
    // China phone number (11 digits starting with 1)
    content = content.replace(/\b(1[3-9]\d)(\d{4})(\d{4})\b/g, '$1****$3')

    // Email address
    content = content.replace(
      /\b([a-zA-Z0-9._%+-])[^@]*(@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})\b/g,
      '$1***$2'
    )

    // China ID card number (18 digits)
    content = content.replace(
      /\b(\d{6})(19|20\d{2})(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])(\d{3}[\dXx])\b/g,
      '$1********$5'
    )

    // Bank card number (16-19 digits)
    content = content.replace(/\b(\d{4})\d{8,11}(\d{4})\b/g, '$1********$2')

    return content
  }
})
```

--------------------------------

### Initialize PageAgent and PageController

Source: https://alibaba.github.io/page-agent/docs/advanced/page-controller

Demonstrates how to initialize the PageAgent with configuration options or by passing a pre-configured PageController instance to PageAgentCore.

```typescript
import { PageAgent } from 'page-agent'
const agent = new PageAgent({
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'your-api-key',
  model: 'gpt-5.2',
  enableMask: true,
  viewportExpansion: 0,
})

import { PageAgentCore } from '@page-agent/core'
import { PageController } from '@page-agent/page-controller'
const pageController = new PageController({
  enableMask: true,
  viewportExpansion: -1,
})

const agentCore = new PageAgentCore({
  pageController,
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'your-api-key',
  model: 'gpt-5.2',
})
```

--------------------------------

### Initialize and Execute Task with PageAgentCore

Source: https://alibaba.github.io/page-agent/docs/advanced/page-agent-core

Demonstrates how to instantiate PageAgentCore with a PageController, attach event listeners for status and activity updates, and execute a task.

```typescript
import { PageAgentCore } from '@page-agent/core';
import { PageController } from '@page-agent/page-controller';

const agent = new PageAgentCore({
  pageController: new PageController({ enableMask: true }),
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'your-api-key',
  model: 'gpt-5.2',
});

// Listen to events for UI display
agent.addEventListener('statuschange', () => {
  console.log('Status:', agent.status);
});

agent.addEventListener('activity', (e) => {
  const activity = (e as CustomEvent).detail;
  console.log('Activity:', activity.type);
});

// Execute task
const result = await agent.execute('Fill in the form with test data');
```

--------------------------------

### PageAgent Basic Usage with LLM Configuration

Source: https://alibaba.github.io/page-agent/docs/advanced/page-agent

Demonstrates the basic usage of the PageAgent class, including initializing it with LLM configuration and executing a task. It shows how to access the result, data, and execution history.

```typescript
import { PageAgent } from 'page-agent'

const agent = new PageAgent({
  // LLM Configuration (required)
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'your-api-key',
  model: 'gpt-5.2',

  // Optional settings
  language: 'en-US',
})

// Execute a task
const result = await agent.execute('Click the login button')

console.log(result.success) // true or false
console.log(result.data)    // Task result description
console.log(result.history) // Full execution history
```

--------------------------------

### Free Testing API Configuration for Qwen (Shell)

Source: https://alibaba.github.io/page-agent/docs/features/models

Provides environment variables for using the free testing API endpoint for Qwen models, proxied via Alibaba Cloud FC. This is intended for technical evaluation and R&D purposes only. It sets the base URL, model name, and API key.

```shell
# qwen3.5-plus (default for demos) or qwen3.5-flash (lighter) LLM_BASE_URL="https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run"
LLM_MODEL_NAME="qwen3.5-plus"
LLM_API_KEY="NA"
```

--------------------------------

### Define InstructionsConfig Interface

Source: https://alibaba.github.io/page-agent/docs/advanced/page-agent-core

Configures the instructions provided to the agent. It supports global system-level instructions and a dynamic callback for page-specific instructions.

```typescript
interface InstructionsConfig {
  /** Global system-level instructions, applied to all tasks */
  system?: string;
  /**
   * Dynamic page-level instructions callback.
   * Called before each step to get instructions for the current page.
   */
  getPageInstructions?: (url: string) => string | undefined;
}
```

--------------------------------

### Custom PageController Implementation

Source: https://alibaba.github.io/page-agent/docs/advanced/page-controller

Guidance on implementing a custom PageController for non-browser environments like Puppeteer or Playwright.

```APIDOC
## Custom Implementation

In non-browser environments (e.g. Puppeteer, Playwright), you can implement a custom PageController. Implement the core methods used by the agent:

```typescript
import { PageAgentCore } from '@page-agent/core'
import type { PageController } from '@page-agent/page-controller'

class PuppeteerPageController implements PageController {
  async getBrowserState() {
    // ... implementation ...
  }

  async clickElement(index: number) {
    // ... implementation ...
  }

  async inputText(index: number, text: string) {
    // ... implementation ...
  }

  async scroll(options: { down: boolean; numPages: number }) {
    // ... implementation ...
  }

  // ... other methods ...
}

const agent = new PageAgentCore({
  pageController: new PuppeteerPageController(),
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'your-api-key',
  model: 'gpt-5.2',
})
```
```

--------------------------------

### Implement Custom PageController

Source: https://alibaba.github.io/page-agent/docs/advanced/page-controller

Shows how to create a custom PageController implementation for non-browser environments like Puppeteer or Playwright by adhering to the required interface.

```typescript
import { PageAgentCore } from '@page-agent/core'
import type { PageController } from '@page-agent/page-controller'

class PuppeteerPageController implements PageController {
  async getBrowserState() { /* ... */ }
  async clickElement(index: number) { /* ... */ }
  async inputText(index: number, text: string) { /* ... */ }
  async scroll(options: { down: boolean; numPages: number }) { /* ... */ }
}

const agent = new PageAgentCore({
  pageController: new PuppeteerPageController(),
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'your-api-key',
  model: 'gpt-5.2',
})
```

--------------------------------

### PageController Methods

Source: https://alibaba.github.io/page-agent/docs/advanced/page-controller

Methods available on the PageController for interacting with the browser and DOM.

```APIDOC
## PageController Methods

### State Queries

| Method | Return Type | Description |
|---|---|---|
| `getBrowserState()` | `Promise<BrowserState>` | Get structured browser state (URL, title, simplified HTML, etc.), automatically calls `updateTree()` to refresh DOM. This is the primary method the agent uses each step. |
| `updateTree()` | `Promise<string>` | Refresh DOM tree and return simplified HTML. Usually not needed manually — `getBrowserState()` calls it automatically. |
| `getCurrentUrl()` | `Promise<string>` | Get current page URL. |

### Element Actions

| Method | Return Type | Description |
|---|---|---|
| `clickElement(index)` | `Promise<ActionResult>` | Click element by index. Index comes from `[N]` markers in simplified HTML. |
| `inputText(index, text)` | `Promise<ActionResult>` | Input text into a form element. |
| `selectOption(index, optionText)` | `Promise<ActionResult>` | Select option in a dropdown element. |
| `scroll(options)` | `Promise<ActionResult>` | Scroll page or specific element vertically. |
| `scrollHorizontally(options)` | `Promise<ActionResult>` | Scroll page or specific element horizontally. |

### Mask Control

| Method | Return Type | Description |
|---|---|---|
| `showMask()` | `Promise<void>` | Show visual mask overlay. Requires `enableMask: true`. |
| `hideMask()` | `Promise<void>` | Hide visual mask overlay. |

### Lifecycle

| Method | Return Type | Description |
|---|---|---|
| `dispose()` | `void` | Clean up all resources (DOM highlights, mask, etc.). Called automatically when agent disposes. |
```

--------------------------------

### Production Authentication with Custom Fetch (JavaScript)

Source: https://alibaba.github.io/page-agent/docs/features/models

Demonstrates a secure method for production environments where Page Agent integrates with a web app. It uses a backend proxy for LLM requests and employs `customFetch` to handle authentication via cookies or other secure methods, avoiding direct exposure of API keys in frontend code.

```javascript
const agent = new PageAgent({
  baseURL: '/api/llm-proxy',
  apiKey: 'NA',
  model: 'gpt-5.1',
  customFetch: (url, init) => fetch(url, { ...init, credentials: 'include' }),
});
```

--------------------------------

### Execute Tasks via PageAgent Extension API

Source: https://alibaba.github.io/page-agent/docs/features/chrome-extension

Demonstrates how to trigger a multi-page task using the PAGE_AGENT_EXT.execute method. It includes configuration for the LLM backend and callback functions for monitoring task progress.

```javascript
const result = await window.PAGE_AGENT_EXT.execute(
	'Search for "page-agent" on GitHub and open the first result',
	{
		baseURL: 'https://api.openai.com/v1',
		apiKey: 'your-api-key',
		model: 'gpt-5.2',
		onStatusChange: status => console.log('Status change:', status),
		onActivity: activity => console.log('Activity:', activity),
		onHistoryUpdate: history => console.log('History update:', history)
	}
)

console.log(result)
```

--------------------------------

### Configure Page Agent with Self-Hosted Ollama Models (JavaScript)

Source: https://alibaba.github.io/page-agent/docs/features/models

Illustrates how to configure PageAgent for self-hosted models using Ollama. The baseURL should point to your local Ollama instance, apiKey is typically set to 'NA', and the model name corresponds to the one served by Ollama. This enables local LLM experimentation.

```javascript
const pageAgent = new PageAgent({
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'NA',
  model: 'qwen3:14b'
});
```

--------------------------------

### Configure Page Agent with MiniMax (JavaScript)

Source: https://alibaba.github.io/page-agent/docs/features/models

Shows the configuration for using PageAgent with MiniMax services. It involves setting the baseURL to the MiniMax API endpoint, providing your specific apiKey, and selecting the model. This is for integrating with MiniMax's LLM offerings.

```javascript
const pageAgent = new PageAgent({
  baseURL: 'https://api.minimax.io/v1',
  apiKey: 'your-minimax-api-key',
  model: 'MiniMax-M2.7'
});
```

--------------------------------

### PageController Configuration

Source: https://alibaba.github.io/page-agent/docs/advanced/page-controller

Configuration options for the PageController, used to customize its behavior during DOM extraction and element interaction.

```APIDOC
## PageController Configuration

### `PageControllerConfig` Interface

| Property | Type | Default | Description |
|---|---|---|---|
| `enableMask` | `boolean` | `false` | Enable visual mask overlay that blocks user interaction during automation. Defaults to true when created via PageAgent. |
| `viewportExpansion` | `number` | `0` | Pixels to expand extraction beyond viewport. Set to -1 to extract the entire page. |
| `interactiveBlacklist` | `(Element | (() => Element))[]` | - | Elements to exclude from interaction. Supports element references or functions returning elements (lazy evaluation). |
| `interactiveWhitelist` | `(Element | (() => Element))[]` | - | Elements to force include for interaction. Supports element references or functions returning elements. |
| `includeAttributes` | `string[]` | - | Additional HTML attributes to include in DOM extraction. Supports wildcard `*` (e.g. `data-*` matches all data- prefixed attributes). Common attributes like `role`, `aria-label` are included by default. |

### Basic Usage Example

```javascript
import { PageAgent } from 'page-agent'

const agent = new PageAgent({
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'your-api-key',
  model: 'gpt-5.2',
  // PageController options
  enableMask: true,
  viewportExpansion: 0,
})
```

### Using with PageAgentCore

```javascript
import { PageAgentCore } from '@page-agent/core'
import { PageController } from '@page-agent/page-controller'

const pageController = new PageController({
  enableMask: true,
  viewportExpansion: -1, // extract full page
})

const agent = new PageAgentCore({
  pageController,
  baseURL: 'https://api.openai.com/v1',
  apiKey: 'your-api-key',
  model: 'gpt-5.2',
})
```
```

--------------------------------

### Define BrowserState and ActionResult Interfaces

Source: https://alibaba.github.io/page-agent/docs/advanced/page-controller

Defines the core data structures used for representing the browser state and the result of automation actions.

```typescript
interface BrowserState {
  url: string
  title: string
  header: string
  content: string
  footer: string
}

interface ActionResult {
  success: boolean
  message: string
}
```

--------------------------------

### Adapt API Parameters with customFetch

Source: https://alibaba.github.io/page-agent/docs/introduction/troubleshooting

Use the customFetch configuration to intercept and modify API requests, adapting parameters for LLM providers that deviate from the OpenAI specification. This is crucial for resolving API request errors like HTTP 400 Bad Request.

```javascript
const agent = new PageAgent({
  // ...
  customFetch: async (url, init) => {
    const body = JSON.parse(init.body)
    // Adapt parameters for your provider
    delete body.stream_options
    return fetch(url, { ...init, body: JSON.stringify(body) })
  },
})
```

--------------------------------

### Define and Register pageAgent Tool (JavaScript)

Source: https://alibaba.github.io/page-agent/docs/features/third-party-agent

This snippet demonstrates how to define a tool for pageAgent integration using JavaScript. It includes the tool's name, description, parameters, and an execute function that calls the pageAgent.execute method. This tool can then be registered with an agent system.

```javascript
// Define tool
const pageAgentTool = {
  name: "page_agent",
  description: "Execute web page operations",
  parameters: {
    type: "object",
    properties: {
      instruction: {
        type: "string",
        description: "Operation instruction"
      }
    },
    required: ["instruction"]
  },
  execute: async (params) => {
    const result = await pageAgent.execute(params.instruction)
    return { success: result.success, message: result.data }
  }
}

// Register to your agent
```

--------------------------------

### Type Definitions

Source: https://alibaba.github.io/page-agent/docs/advanced/page-controller

Defines the structure of data returned by PageController methods.

```APIDOC
## Type Definitions

### `BrowserState` Interface

Structured browser state returned by `getBrowserState()`, used directly to build LLM prompts.

```typescript
interface BrowserState {
  url: string
  title: string
  header: string // page info + scroll position
  content: string // simplified HTML of interactive elements
  footer: string // scroll hint
}
```

### `ActionResult` Interface

```typescript
interface ActionResult {
  success: boolean
  message: string
}
```
```

--------------------------------

### PageAgent UI Panel Control

Source: https://alibaba.github.io/page-agent/docs/advanced/page-agent

Illustrates how to control the built-in UI panel of the PageAgent instance. It covers showing/hiding the panel, expanding/collapsing the history view, resetting its state, and disposing of it.

```typescript
// Show/hide the panel agent.panel.show()
agent.panel.hide()

// Expand/collapse history view
agent.panel.expand()
agent.panel.collapse()

// Reset panel state
agent.panel.reset()

// Dispose panel (called automatically when agent disposes)
agent.panel.dispose()
```

--------------------------------

### Override or Remove Built-in Tools

Source: https://alibaba.github.io/page-agent/docs/features/custom-tools

Shows how to modify the default behavior of Page Agent by overriding existing tools or setting them to null to disable them.

```typescript
const pageAgent = new PageAgent({
  customTools: {
    scroll: null, // remove scroll tool
    execute_javascript: null, // remove script execution
  },
});
```

--------------------------------

### Configure PageAgent Extension Authentication

Source: https://alibaba.github.io/page-agent/docs/features/chrome-extension

Sets the authorization token in local storage to enable the window.PAGE_AGENT_EXT API. This token must only be provided to trusted applications to prevent unauthorized browser control.

```javascript
localStorage.setItem('PageAgentExtUserAuthToken', '<your-token-from-extension>')
```

--------------------------------

### Define ExecutionResult Interface

Source: https://alibaba.github.io/page-agent/docs/advanced/page-agent-core

Defines the structure for the final output of an agent execution. It includes a success flag, the resulting data string, and a history of events.

```typescript
interface ExecutionResult {
  success: boolean;
  data: string;
  history: HistoricalEvent[];
}
```

--------------------------------

### Define PageAgent TypeScript Interfaces

Source: https://alibaba.github.io/page-agent/docs/features/chrome-extension

Provides the necessary TypeScript type definitions and global window augmentation for the PageAgent extension API. This allows for type-safe interaction with the extension's execution and status tracking methods.

```typescript
import type { 	AgentActivity, 	AgentStatus, 	ExecutionResult, 	HistoricalEvent } from '@page-agent/core'

interface ExecuteConfig {
	baseURL: string
	apiKey: string
	model: string
	includeInitialTab?: boolean
	onStatusChange?: (status: AgentStatus) => void
	onActivity?: (activity: AgentActivity) => void
	onHistoryUpdate?: (history: HistoricalEvent[]) => void
}

type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>

declare global {
	interface Window {
		PAGE_AGENT_EXT_VERSION?: string
		PAGE_AGENT_EXT?: {
			version: string
			execute: Execute
			stop: () => void
		}
	}
}
```

--------------------------------

### API Definition for PageAgentConfig

Source: https://alibaba.github.io/page-agent/docs/features/data-masking

Defines the `PageAgentConfig` interface, specifically highlighting the `transformPageContent` hook. This hook allows for processing page content after DOM extraction and simplification, before it's sent to an LLM. It can be an asynchronous function returning a string or a synchronous function returning a string.

```typescript
interface PageAgentConfig {
  /**
   * Transform page content before sending to LLM.
   * Called after DOM extraction and simplification.
   */
  transformPageContent?: (content: string) => Promise<string> | string
}
```

--------------------------------

### Define AgentActivity Discriminated Union

Source: https://alibaba.github.io/page-agent/docs/advanced/page-agent-core

Represents the various states and activities an agent can undergo during its lifecycle. It covers thinking, executing tools, completion, retries, and error states.

```typescript
type AgentActivity = 
  | { type: 'thinking' }
  | { type: 'executing'; tool: string; input: unknown }
  | { type: 'executed'; tool: string; input: unknown; output: string; duration: number }
  | { type: 'retrying'; attempt: number; maxAttempts: number }
  | { type: 'error'; message: string };
```

--------------------------------

### transformPageContent Hook

Source: https://alibaba.github.io/page-agent/docs/features/data-masking

The transformPageContent hook allows developers to intercept and modify the extracted page content before it is processed by the LLM.

```APIDOC
## transformPageContent Hook

### Description
Processes page content after DOM extraction and simplification. This is the primary method for masking sensitive data or modifying page information before sending it to the LLM.

### Method
Function Hook

### Endpoint
PageAgentConfig.transformPageContent

### Parameters
#### Request Body
- **content** (string) - Required - The raw string content extracted from the page.

### Request Example
```javascript
const agent = new PageAgent({
  transformPageContent: async (content) => {
    return content.replace(/sensitive-data/g, '***');
  }
});
```

### Response
#### Success Response
- **string** - The transformed/masked content string.

### Response Example
"Masked content string ready for LLM processing."
```

--------------------------------

### Stop PageAgent Task Execution

Source: https://alibaba.github.io/page-agent/docs/features/chrome-extension

Invokes the stop method on the PAGE_AGENT_EXT interface to immediately halt any currently running automation tasks.

```javascript
window.PAGE_AGENT_EXT.stop()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.