Operator Agent：视觉驱动的计算机交互

Operator Agent：视觉驱动的计算机交互

学习目标

理解 Khoj 的 Operator 系统架构：Agent 与环境的分离、三种 Agent 实现、两种环境、以及视觉驱动的迭代循环。

前置知识

本章涉及 Operator Agent 的通用模式，建议先阅读：

• 视觉驱动的 Operator Agent 模式

下文假设你已理解上述概念，直接聚焦 Khoj 的具体实现。

项目实践

系统总览

Khoj 的 Operator 系统（src/khoj/processor/operator/，约 4500 行代码）是整个项目中最复杂的子系统之一。它允许 Agent 通过视觉感知直接操作浏览器或计算机桌面，无需专用 API。

Agent-Environment 分离架构

三种 Agent 实现

Agent	行	支持模型	特点
AnthropicOperatorAgent	635	Claude 3.5/3.7 Sonnet, Sonnet 4, Opus 4	使用 Anthropic computer use tool，最成熟
OpenAIOperatorAgent	472	GPT-4o	当前被 False 门控禁用，保留待验证
BinaryOperatorAgent	405	ui-tars-1.5	使用专用 GUI grounding 模型，需要 OpenAI 兼容 API 服务

AnthropicOperatorAgent 是目前唯一可用的实现。它将 Anthropic 的 computer use tool 的 30+ 种动作（点击、拖拽、滚动、按键等）映射为 Khoj 内部的 OperatorAction 数据类，再交由 Environment 执行。

两种环境实现

BrowserEnvironment（约 400 行）：

• 基于 Playwright 自动化浏览器
• get_state(): 截屏 + 获取当前 URL
• step(action): 将 ClickAction、TypeAction 等映射为 Playwright API
• 记录 visited_urls 用于调试和结果追踪

ComputerEnvironment（约 660 行）：

• 基于 Docker 容器运行完整桌面环境
• 通过 VNC 截屏，通过 xdotool 执行鼠标键盘操作
• 支持 Docker provider（容器化部署）
• 需要 vision-enabled 模型

迭代循环

Operator 的核心循环（约 80 行）：

while iterations < max_iterations and not task_completed:
    1. env_state = await environment.get_state()       # 截屏
    2. agent_result = await operator_agent.act(env_state)  # 决策
    3. for action in agent_result.actions:
           env_step = await environment.step(action)    # 执行
    4. operator_agent.add_action_results(env_steps, agent_result)  # 反馈
    5. task_completed = not agent_result.actions        # 终止判断

每次迭代：

1. 截屏获取环境状态
2. 视觉模型分析截屏，输出动作指令
3. 在环境中执行动作
4. 将执行结果反馈给 Agent
5. 如果 Agent 不再输出动作 → 任务完成

配置与限制

环境变量:
  KHOJ_OPERATOR_ENABLED: 是否启用 Operator 功能
  KHOJ_OPERATOR_ITERATIONS: 最大迭代次数（默认 100）

模型要求:
  - 必须支持视觉输入
  - 当前仅支持 Anthropic 模型（其他被门控禁用）

WebSocket 中断传递

与主 Agent 循环一致，Operator 任务也支持中断：

• cancellation_event: 客户端断连时设置，优雅退出循环
• interrupt_queue: 用户发送新指令，作为新的 user 消息加入对话

当用户输入请求（如需要填写个人信息）时，Agent 发出 RequestUserAction，循环暂停但不关闭环境，等待用户输入后继续。

问题与规避

问题	影响	规避策略
视觉模型调用成本高	100 次迭代 × 视觉模型 = 大量费用	默认 100 次上限；建议用户拆分小任务
环境状态不一致	页面加载慢导致截屏不完整	Agent 可以自主决定 WaitAction
Docker 资源泄漏	未关闭的容器占用资源	finally 块确保 environment.close() 执行
仅 Anthropic 可用	无法使用 OpenAI 模型做 Operator	OpenAIOperatorAgent 已实现但被门控禁用，待验证
BinaryOperatorAgent 需要自建模型	ui-tars-1.5 需要自行部署	需要 OpenAI 兼容 API 端点

设计取舍

为什么将 OpenAIOperatorAgent 和 BinaryOperatorAgent 门控禁用？

这两个 Agent 已经实现（代码量不小），但被 False 条件门控。这是 Khoj 的渐进式发布策略：代码已经写好了，但实际效果和稳定性还不够，不暴露给用户。一旦验证通过，只需将门控改为 True 即可启用。

为什么最大迭代次数默认 100？

100 次是一个安全上限。一次完整的浏览器任务通常 10-30 次迭代即可完成。100 次意味着即使 Agent 陷入循环，也会在合理时间内停止。超过 100 次后返回当前结果 + 警告，建议用户拆分任务。

参考来源

• Anthropic Computer Use 文档
• Playwright 文档
• UI-TARS 论文