Skip to content

06-agent-interface.md

Latest commit

 

History

History
174 lines (143 loc) · 8.51 KB

06-agent-interface.md

File metadata and controls

174 lines (143 loc) · 8.51 KB
Raw

06 · Agent 接口

目标 G5：让任意 Agent（包括驱动本项目的 AI 助手自己）零摩擦地发现、探索、回放、管理技能。 主接口是 MCP Server（贴合 Cursor/Claude 等 Agent 生态），并与 Skills 概念对齐；另提供本地 gRPC/REST 供程序化调用。

本篇是 inbound 方向（Agent → 底座）。底座反向回调 Agent 的 outbound（Cognition Port） 见 10；批量执行工具见 11；observe 的多模态细节见 12。

1. 接口分层：两种调用姿势

flowchart TB
    subgraph AGENT["Agent（本 AI / 其他）"]
        HL["高层：给意图，要结果"]
        LL["低层：自己一步步驱动浏览器"]
    end
    subgraph MCPTOOLS["MCP 工具面"]
        subgraph HIGH["高层工具(推荐默认)"]
            H1["explore_task"]
            H2["run_skill"]
            H3["list_skills / search_skills"]
            H4["get_skill / diff_skill"]
            H5["generate_template / run_batch (见 11)"]
        end
        subgraph LOW["低层工具(精细控制/调试)"]
            L1["open_session / close_session"]
            L2["observe(多模态:截图+AX+DOM+OCR+候选, 见 12)"]
            L3["act(单步拟人动作)"]
            L4["extract(按schema抽取)"]
            L5["approve(处理审批/升级点)"]
        end
    end
    HL --> HIGH --> CORE["praxisd 控制面"]
    LL --> LOW --> CORE
Loading
  • 高层优先：多数场景 Agent 只需 explore_task（首次）+ run_skill（复用）。这把复杂度收敛进底座，符合"让 Agent 更顺畅"的初衷。
  • 低层可选：需要精细控制或调试时，Agent 可用 observe/act/extract 亲自驱动（借鉴 Stagehand 的 observe→act 与 Skyvern 的 blocks 粒度）。observe 返回带 %变量% 占位的候选动作，便于安全审阅后再 act。

2. 核心 MCP 工具契约（草案）

完整参数以 07 技能包规范 为准；这里给 Agent 可见的工具签名与语义。

工具 语义 关键入参 返回 Token
explore_task NL 意图→探索→结晶技能→产出结果 intent, target?, output_schema?, constraints(site_policy/预算), save_as? result, skill_ref, run_id, cost 花
run_skill 0 Token 回放已发布技能 skill_ref, inputs{}, identity?, tier? result, run_id, heal_events, cost(=0期望) 0
search_skills 语义检索可用技能 query, site? [{skill_ref, desc, trust, io_schema}] 0
get_skill / diff_skill 查看技能定义/版本差异 skill_ref, version? 技能定义 / diff 0
observe 观察当前页返回多模态上下文+候选动作 session, instruction?, modalities? {ax,dom,screenshot,ocr,candidates[含%占位%]} 0（底座采集）
act 执行单步拟人动作 session, ref 或 action new_state 0
extract 按 schema 抽取结构化数据 session, schema data 0
generate_template 由技能 schema 生成参数模板 skill_ref, format(csv/xlsx) 模板文件 0
run_batch 导入表格→批量 0 Token 回放 skill_ref, file, identity_policy? batch_id, summary, export_ref 0（自愈另计）
open_session/close_session 显式管理隐身会话 domain, identity?, tier? session 0
approve 处理审批点/升级(硬挑战/高风险) run_id, decision resumed 0

说明：observe 本身是底座 0 Token 采集（多模态感知，见 12）；消耗 Token 的是 Agent 拿到上下文后自己的推理（发生在 Agent 侧，I-4/I-6）。

设计约定：

  • run_skill 承诺 0 Token：若返回 cost>0，必然是触发了自愈，返回里带 heal_events 说明（对应 I-4/SC7 的可见性）。
  • 机密永不出现在工具入参：Agent 传业务参数，凭据在 Vault，工具入参里最多是 %vault:...% 引用（I-5）。
  • 升级人工经 approve 回环：硬挑战/高风险动作暂停为 NeedsHuman，Agent 或人经 approve 恢复（默会确认点显式化）。

3. 与 Skills 概念对齐

Agent-RPA 的"技能包"设计为可被 Agent 生态当作 Skill 发现与调用：

flowchart LR
    subgraph SKILLPKG["Agent-RPA 技能包"]
        MANIFEST["SKILL.md 风格清单<br/>name/description/when-to-use/io schema"]
        GRAPH["动作图 + 定位器 + 断言(内部)"]
    end
    MANIFEST -->|暴露为| MCPTOOL["MCP 工具/资源<br/>(可被 Agent 检索到)"]
    MANIFEST -->|可导出为| SKILLDIR["Skill 目录条目<br/>(description + 调用说明)"]
    AGENT["任意 Agent"] -->|按 description 决定何时用| MCPTOOL
Loading
  • 清单即发现入口：每个技能带 description 与 when_to_use，让 Agent 像挑选 Skill 一样按语义命中（"要在电商比价 → 命中 search-and-compare@ecom-X"）。
  • 动作图对 Agent 不可见：Agent 只需知道"给什么、得什么"（io schema），内部的定位器/断言/隐身细节被底座封装——这正是"底座"的意义。
  • 可被 workflow-use/Stagehand 式的"技能即 MCP 工具"消费（借鉴其 roadmap "Expose workflows as MCP tools"）。

4. 端到端调用样例（本 AI 视角）

4.1 首次探索并结晶（旅程 A）

// Agent → explore_task
{
  "intent": "在 ecom-X 搜索『无线降噪耳机』，取前10条的标题/价格/评分，按性价比排序",
  "target": "https://ecom-x.example",
  "output_schema": {
    "items": [{ "title": "string", "price": "number", "rating": "number" }]
  },
  "constraints": { "site_policy": "default", "budget_tokens": 200000 },
  "save_as": "search-and-compare@ecom-x"
}
// ← 返回
{ "result": { "items": [/* ... */] },
  "skill_ref": "search-and-compare@ecom-x@1.0.0",
  "run_id": "run_abc", "cost": { "tokens": 143210 } }

4.2 换参 0 Token 复用（旅程 B）

// Agent → run_skill
{ "skill_ref": "search-and-compare@ecom-x", "inputs": { "query": "机械键盘", "topN": 10 } }
// ← 返回
{ "result": { "items": [/* ... */] }, "run_id": "run_def",
  "heal_events": [], "cost": { "tokens": 0 } }

4.3 触发自愈（旅程 C，页面漂移）

// run_skill 返回：L1 自愈成功、技能自动升版
{ "result": { "items": [/* ... */] }, "run_id": "run_ghi",
  "heal_events": [{ "step": 2, "level": "L1", "fixed": "search box relocated by AX role+name",
                    "skill_bumped_to": "1.0.1" }],
  "cost": { "tokens": 0 } }

5. 交互时序（高层路径）

sequenceDiagram
    autonumber
    participant AI as 本 AI(Agent)
    participant MCP as Agent-RPA MCP
    participant CORE as praxisd
    participant POOL as Browser Pool

    AI->>MCP: search_skills("电商比价 ecom-x")
    MCP-->>AI: 命中 search-and-compare@ecom-x (trust 0.94)
    AI->>MCP: run_skill(skill, {query:"机械键盘"})
    MCP->>CORE: 创建 replay Run(准入检查)
    CORE->>POOL: 申请隐身会话(同身份/记忆档位)
    POOL-->>CORE: 会话就绪
    CORE->>CORE: 0 Token 解释执行(必要时自愈)
    CORE-->>MCP: 结构化结果 + cost:0
    MCP-->>AI: result
Loading

6. 错误与升级语义（对 Agent 友好）

情况 返回给 Agent 建议 Agent 行为
技能不存在/失效 SKILL_NOT_FOUND / DEPRECATED 改用 explore_task 重探索
触发硬挑战 NEEDS_HUMAN(reason=captcha) + run_id 提示人处理 → approve 恢复
高风险动作待批 NEEDS_APPROVAL(action=checkout) 呈报人类审批 → approve
被拦升档中 TIER_ESCALATED(from=T1,to=T2) 无需干预，等待
预算超限 BUDGET_EXCEEDED 缩小范围/提高预算重试
  • 升级点对 Agent 是显式返回而非静默失败，让 Agent 能把"需要人类默会判断"的地方交回给人。

验收检查表（本篇）

  • 高层(explore_task/run_skill/run_batch)与低层(observe/act/extract)双姿势齐备（SC6）。
  • run_skill/run_batch 默认 0 Token，cost>0 必附 heal_events（I-4）。
  • observe 返回多模态上下文（见 12），采集本身 0 Token（I-6）。
  • generate_template/run_batch 打通参数模板→批量执行（见 11）。
  • 技能对齐 Skills：带 description/when_to_use/io schema，可被 Agent 语义发现。
  • 机密不出现在工具入参，只用 %vault:...%（I-5）。
  • 硬挑战/高风险以 NEEDS_HUMAN/NEEDS_APPROVAL 显式回环（SC8/默会确认点）。