webagent — Actions Catalog

Agent 能用的所有 tool。LLM 透過 function calling 呼叫。

設計原則

每個 action 有明確 input schema（Zod / JSON Schema）
每個 action 都是 idempotent 或明確標記 side-effect
失敗回標準化 error（不 throw 給 agent loop）
DOM 操作前先 query 一次確認存在，找不到回 { ok: false, reason: 'not_found' }

完整清單（v1 內建 19 個）

導航 / 頁面控制

Action	參數	行為
`navigate`	`{ path: string }`	SPA-friendly 換頁（發 event，host 決定怎麼走）
`back`	`{}`	`history.back()`
`reload`	`{}`	`location.reload()`
`scroll_to`	`{ selector: string }`	平滑滾到該元素
`wait`	`{ ms: number }`	等待（最多 5000ms）
`wait_for`	`{ selector: string, timeout?: number }`	等元素出現（預設 5000ms）

DOM 互動

Action	參數	行為
`click`	`{ selector: string }`	點擊元素
`fill_input`	`{ selector: string, value: string }`	填入框
`select_option`	`{ selector: string, value: string }`	`<select>` 選項
`submit_form`	`{ selector: string }`	送出 form
`clear_input`	`{ selector: string }`	清空欄位
`set_text`	`{ selector: string, text: string }`	改 contentEditable 文字

視覺 overlay（給用戶看）

Action	參數	行為
`highlight`	`{ selector, color?, label? }`	加底色 + 可選 label
`border`	`{ selector, color?, label? }`	加框
`spotlight`	`{ selector }`	周圍 dim + 中間亮
`inject`	`{ selector, text, position? }`	插入文字（before / after）
`clear_overlays`	`{}`	清除所有 overlay

跟用戶溝通

Action	參數	行為
`show_subtitle`	`{ text: string }`	顯示字幕條給用戶看
`ask_user`	`{ question: string }`	暫停，等用戶回答純文字
`render_a2ui_surface`	`{ surface: A2UISurface, placement?: 'center' \| 'inline' \| 'dock' }`	渲染 A2UI form / card，等用戶提交

結束

Action	參數	行為
`done`	`{ summary?: string }`	任務完成，session 結束

Action Result 標準格式

type ActionResult =
  | { ok: true; data?: any }
  | { ok: false; reason: ActionFailureReason; message?: string };

type ActionFailureReason =
  | 'not_found'       // selector 沒找到
  | 'not_visible'     // 元素存在但不可見
  | 'not_interactive' // 元素 disabled / readonly
  | 'timeout'         // wait_for 超時
  | 'navigation'      // 換頁中途被打斷
  | 'unknown';

Agent loop 把 result 加入 session.steps，下一輪 LLM 看得到失敗原因，可以自我修正。

Selector 規範

LLM 回的 selector 必須是CSS selector，但限制：

只能用 tag / id / class / [data-*] attribute / :nth-child()
禁止 :has()、:not() 等可能 NodeList 大爆炸的選擇器
禁止 *（全選）
找到多個元素時，預設取第一個可見的，但 result.data 會帶 { matched: N, used: 0 } 提示

複雜選擇用 data-webagent-id 屬性（DOM Reader 會自動加 fallback id）。

自訂 action 範例

import { z } from 'zod';

agent.config.customActions = [
  {
    name: 'open_chat_panel',
    description: '在右側打開聊天面板',
    parameters: z.object({
      initialMessage: z.string().optional(),
    }),
    handler: async ({ initialMessage }, ctx) => {
      myUI.openChatPanel(initialMessage);
      return { ok: true };
    },
  },
];

Action vs Direct API

Action 是「LLM 可呼叫」的。如果你要 host 直接調用某些行為（不透過 LLM），用 agent.executeAction(name, params) 直接執行，不會記入 session.steps。

不會做的 action（明確列出避免被問）

❌ screenshot — webagent 不主動截圖；如果要視覺輸入用 image content part
❌ eval_js — 太危險，不開
❌ fetch — 改用 custom action 包，不要直接讓 LLM 發任意請求
❌ localStorage_set/get — 改用 custom action