+
PageAgentCore
+
+
+ {isZh
+ ? 'PageAgentCore 是不带 UI 的核心 Agent 类。用于需要自定义 UI 或无头运行的场景。'
+ : 'PageAgentCore is the core Agent class without UI. Use it for custom UI or headless scenarios.'}
+
+
+ {/* When to use */}
+
+
+ {isZh ? '何时使用 PageAgentCore' : 'When to Use PageAgentCore'}
+
+
+ {isZh ? '需要自定义 UI 界面' : 'Need a custom UI interface'}
+ {isZh ? '在自动化测试中无头运行' : 'Running headless in automated tests'}
+
+ {isZh
+ ? '在非浏览器环境运行（需自定义 PageController）'
+ : 'Running in non-browser environments (requires custom PageController)'}
+
+
+ {isZh
+ ? '将 PageAgent 嵌入其他 Agent 系统'
+ : 'Embedding PageAgent in other agent systems'}
+
+
+
+
+ {/* Basic Usage */}
+
+ {isZh ? '基本用法' : 'Basic Usage'}
+ {
+ console.log('Status:', agent.status)
+})
+
+agent.addEventListener('historychange', () => {
+ console.log('History:', agent.history)
+})
+
+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')`}
+ />
+
+
+
+
+ {/* LLM Configuration */}
+
+ LLMConfig
+
+ {isZh
+ ? '配置与大语言模型的连接参数。支持 OpenAI 兼容的 API。'
+ : 'Configure connection parameters for the language model. Supports OpenAI-compatible APIs.'}
+
+
+
+ {/* Agent Configuration */}
+
+ AgentConfig
+
+ {isZh
+ ? '配置 Agent 的行为、生命周期钩子和扩展能力。'
+ : 'Configure agent behavior, lifecycle hooks, and extension capabilities.'}
+
+ ',
+ status: 'experimental',
+ description: isZh
+ ? '自定义工具，可扩展或覆盖内置工具。设为 null 可移除工具。'
+ : 'Custom tools to extend or override built-in tools. Set to null to remove a tool.',
+ },
+ {
+ name: 'instructions',
+ type: 'InstructionsConfig',
+ description: isZh
+ ? '指导 Agent 行为的指令配置'
+ : 'Instructions to guide agent behavior',
+ },
+ {
+ name: 'transformPageContent',
+ type: '(content: string) => string | Promise',
+ description: isZh
+ ? '发送给 LLM 前转换页面内容，可用于数据脱敏'
+ : 'Transform page content before sending to LLM, useful for data masking',
+ },
+ {
+ name: 'experimentalScriptExecutionTool',
+ type: 'boolean',
+ defaultValue: 'false',
+ status: 'experimental',
+ description: isZh
+ ? '启用实验性 JavaScript 执行工具'
+ : 'Enable experimental JavaScript execution tool',
+ },
+ ]}
+ />
+
+ InstructionsConfig
+ string | undefined | null',
+ description: isZh
+ ? '动态页面级指令回调，在每个步骤前调用'
+ : 'Dynamic page-level instructions callback, called before each step',
+ },
+ ]}
+ />
+
+
+ {/* Lifecycle Hooks */}
+
+ {isZh ? '生命周期钩子' : 'Lifecycle Hooks'}
+ void | Promise',
+ description: isZh ? '每个步骤执行前调用' : 'Called before each step execution',
+ status: 'experimental',
+ },
+ {
+ name: 'onAfterStep',
+ type: '(history: HistoricalEvent[]) => void | Promise',
+ description: isZh ? '每个步骤执行后调用' : 'Called after each step execution',
+ status: 'experimental',
+ },
+ {
+ name: 'onBeforeTask',
+ type: '() => void | Promise',
+ description: isZh ? '任务开始前调用' : 'Called before task starts',
+ status: 'experimental',
+ },
+ {
+ name: 'onAfterTask',
+ type: '(result: ExecutionResult) => void | Promise',
+ description: isZh ? '任务结束后调用' : 'Called after task ends',
+ status: 'experimental',
+ },
+ {
+ name: 'onDispose',
+ type: '(reason?: string) => void',
+ description: isZh ? 'Agent 销毁时调用' : 'Called when agent is disposed',
+ status: 'experimental',
+ },
+ ]}
+ />
+
+
+ {/* PageController Configuration */}
+
+ PageControllerConfig
+
+ {isZh
+ ? '配置 DOM 提取、元素交互和视觉反馈。'
+ : 'Configure DOM extraction, element interaction, and visual feedback.'}
+
+ Element))[]',
+ description: isZh ? '要排除的交互元素列表' : 'Elements to exclude from interaction',
+ },
+ {
+ name: 'interactiveWhitelist',
+ type: '(Element | (() => Element))[]',
+ description: isZh
+ ? '要强制包含的交互元素列表'
+ : 'Elements to force include for interaction',
+ },
+ {
+ name: 'include_attributes',
+ type: 'string[]',
+ description: isZh
+ ? '在 DOM 提取中包含的额外属性'
+ : 'Additional attributes to include in DOM extraction',
+ },
+ ]}
+ />
+
+
+
+
+ {/* Properties */}
+
+ {isZh ? '属性' : 'Properties'}
+ ',
+ description: isZh ? '可用工具的 Map' : 'Map of available tools',
+ },
+ {
+ name: 'onAskUser',
+ type: '(question: string) => Promise',
+ description: isZh
+ ? 'Agent 需要用户输入时的回调。未设置则禁用 ask_user 工具。'
+ : 'Callback when agent needs user input. If not set, ask_user tool is disabled.',
+ },
+ ]}
+ />
+
+
+ {/* Methods */}
+
+ {isZh ? '方法' : 'Methods'}
+ ',
+ description: isZh
+ ? '执行任务并返回结果。包含 success、data 和 history 字段。'
+ : 'Execute a task and return result. Contains success, data, and history fields.',
+ },
+ {
+ name: 'pushObservation(content: string)',
+ type: 'void',
+ description: isZh
+ ? '向历史流推送一个观察事件，会在下一步时被 LLM 看到'
+ : 'Push an observation to history stream, will be seen by LLM in next step',
+ },
+ {
+ name: 'emitActivity(activity: AgentActivity)',
+ type: 'void',
+ description: isZh
+ ? '发出活动事件用于 UI 反馈'
+ : 'Emit activity event for UI feedback',
+ },
+ {
+ name: 'dispose(reason?: string)',
+ type: 'void',
+ description: isZh
+ ? '销毁 Agent 并清理资源'
+ : 'Dispose the agent and clean up resources',
+ },
+ ]}
+ />
+
+
+ {/* Events */}
+
+ {isZh ? '事件' : 'Events'}
+
+ {isZh ? (
+ <>
+ PageAgentCore 继承自 EventTarget ，提供以下事件：
+
+ ) : (
+ <>
+ PageAgentCore extends EventTarget and provides the following
+ events:
+
+ )}
+
+ ',
+ description: isZh
+ ? '实时活动反馈（短暂状态，仅用于 UI）。类型包括：thinking, executing, executed, retrying, error'
+ : 'Real-time activity feedback (transient, UI only). Types: thinking, executing, executed, retrying, error',
+ },
+ {
+ name: 'dispose',
+ type: 'Event',
+ description: isZh ? 'Agent 被销毁时触发' : 'Fired when agent is disposed',
+ },
+ ]}
+ />
+
+
+
+
+ {/* ExecutionResult */}
+
+
+ {/* AgentActivity */}
+
+
+ {/*
*/}
+
+
PageAgent
+
+
+ {isZh
+ ? 'PageAgent 是带有内置 UI 面板的完整 Agent 类。它继承自 PageAgentCore，并自动创建交互面板。'
+ : 'PageAgent is the complete Agent class with built-in UI panel. It extends PageAgentCore and automatically creates an interactive panel.'}
+
+
+ {/* When to use */}
+
+
+ {isZh ? '何时使用 PageAgent' : 'When to Use PageAgent'}
+
+
+ {isZh
+ ? '在大多数场景下，你应该使用 PageAgent。它提供了开箱即用的完整体验：'
+ : 'In most cases, you should use PageAgent. It provides a complete out-of-the-box experience:'}
+
+
+
+ {isZh
+ ? '内置 UI 面板，显示任务进度、Agent 思考过程和操作结果'
+ : 'Built-in UI panel showing task progress, agent thinking, and action results'}
+
+
+ {isZh
+ ? '支持 ask_user 工具，Agent 可以向用户提问'
+ : 'Supports ask_user tool for agent to ask questions to users'}
+
+
+
+
+ {/* Basic Usage */}
+
+ {isZh ? '基本用法' : 'Basic Usage'}
+
+
+ {/* Class Definition */}
+
+ {isZh ? '类定义' : 'Class Definition'}
+
+ {isZh ? (
+ <>
+ PageAgent 继承自{' '}
+
+
+
+ {/* Configuration */}
+
+ {isZh ? '配置' : 'Configuration'}
+
+ {isZh
+ ? 'PageAgent 使用与 PageAgentCore 相同的配置接口。'
+ : 'PageAgent uses the same configuration interface as PageAgentCore.'}
+
+
+ {isZh ? (
+ <>
+ 完整配置请参考{' '}
+
+
+
+ {/* Panel Property */}
+
+ {isZh ? 'Panel 属性' : 'Panel Property'}
+
+ {isZh
+ ? 'PageAgent 自动创建一个 Panel 实例。你可以通过 panel 属性访问它来控制 UI：'
+ : 'PageAgent automatically creates a Panel instance. You can access it via the panel property to control the UI:'}
+
+
+ {isZh ? 'Panel 方法' : 'Panel Methods'}
+
+
+ {/* Comparison with PageAgentCore */}
+
+
+ {isZh ? 'PageAgent vs PageAgentCore' : 'PageAgent vs PageAgentCore'}
+
+
+
+
+
+
+ {isZh ? '特性' : 'Feature'}
+
+
+ PageAgent
+
+
+ PageAgentCore
+
+
+
+
+
+
+ {isZh ? 'UI 面板' : 'UI Panel'}
+
+ ✓
+ -
+
+
+
+ {isZh ? 'Headless 模式' : 'Headless Mode'}
+
+ -
+ ✓
+
+
+
+ {isZh ? '自定义 PageController' : 'Custom PageController'}
+
+ ✓
+ ✓
+
+
+
+ {isZh ? '适用场景' : 'Use Case'}
+
+
+ {isZh ? '网页集成' : 'Web integration'}
+
+
+ {isZh ? '自定义 UI / 无头' : 'Custom UI / Headless'}
+
+
+
+
+
+