跳到主要内容

数据截至 (上游 commit bffdb59c60cb)

Agent S — 架构与原理

30 秒导读: Agent S 是一个让 AI "像人一样用电脑"的开源框架——它截屏、思考、然后真的去移动鼠标、敲键盘,完成"把这张表的 B 列求和""在浏览器里改个设置"这种跨应用任务。最新的 Agent S3 是第一个在 OSWorld 基准上超过人类水平(72.6%)的系统。它的核心设计是两段式:一个强推理模型(如 GPT-5)负责看屏和决定下一步,一个独立的视觉定位模型(如 UI-TARS)专门把"点右上角那个保存图标"翻译成精确的屏幕坐标。

1. 这是什么(零基础也能懂)​

一句话定义: Agent S 是一个computer-use agent(电脑操作智能体)——给它一句自然语言指令和一张屏幕截图,它就能自主地点鼠标、敲键盘,把任务在真实操作系统上做完。

解决什么问题 / 给谁用:

假设你想让 AI 帮你干这种活:

"打开这个 LibreOffice 表格,把 B 列所有数字求和填到 B20,然后另存为 PDF。"

这件事没有 API 可调——它全发生在图形界面里:要找到表格图标、双击、点中单元格、输入公式、走菜单导出。Agent S 就是把"看屏幕 → 想 → 操作"这个人类循环自动化。它面向研究者和开发者,用来构建能操作真实桌面(Windows / macOS / Linux)的 GUI agent。

它能做什么:

  • 跨应用完成任务:文件管理、表格、文档、浏览器、系统设置。
  • 三大操作系统通吃(darwin / linux / windows),动作翻译会按平台分叉。
  • 把"纯靠写代码就能干"的子任务(如批量数据处理)甩给一个内置的 Code Agent 去跑 Python/Bash。
  • 通过 Behavior Best-of-N 在测试期跑多次、选最优,把准确率再往上推。

用起来什么样:

命令行跑一条真实任务(摘自 README.md):

# 主推理模型用 GPT-5,定位模型用自托管的 UI-TARS-1.5-7B
agent_s \
    --provider openai --model gpt-5-2025-08-07 \
    --ground_provider huggingface \
    --ground_url http://localhost:8080 \
    --ground_model ui-tars \
    --grounding_width 1920 --grounding_height 1080 \
    --task "Open the file report.xlsx and sum column B into B20"

注意命令里有两组模型参数:--model 是"大脑",--ground_* 是"眼睛+手"的坐标定位器。这正是 Agent S 架构的核心——见下一节。

一句话直觉/类比: 把它想成一个会读屏的项目经理 + 一个只管"那东西在屏幕哪个像素"的瞄准手。经理(推理模型)说"点那个红色删除按钮",瞄准手(定位模型)负责回答"它在 (1340, 88)",然后系统替你按下去。

2. 顶层全景(它大概怎么转)​

Agent S3 的一步循环长这样(每一步都从一张新截图开始):

  自然语言任务  ┐
               │
  当前屏幕截图  ─┤
               ▼
     ┌───────────────────────┐   产出一段自然语言计划 +
     │  Worker(大脑模型)    │   一行"动作代码"如
     │  + 可选 Reflection    │   agent.click("红色删除按钮")
     └──────────┬────────────┘
                │ 这行代码里的"红色删除按钮"还只是文字
                ▼
     ┌───────────────────────┐   把英文描述送给定位模型,
     │  ACI / OSWorldACI     │   拿回 (x, y),再缩放到真实分辨率
     │  (Agent-Computer IF)  │
     └──────────┬────────────┘
                │ 产出可执行的 pyautogui 代码字符串
                ▼
     ┌───────────────────────┐   exec() 真正移动鼠标/键盘
     │  pyautogui 在真机执行  │
     └──────────┬────────────┘
                ▼
          新截图 → 回到顶部,直到 agent.done()

主要部件一句话职责:

部件干什么在哪个文件
AgentS3顶层封装,把任务和观测转交给 Workergui_agents/s3/agents/agent_s.py
Worker主循环大脑:看屏 → 生成计划 + 一个动作;还驱动反思gui_agents/s3/agents/worker.py
OSWorldACI动作接口:每个动作(click/type/…)在执行时调用定位模型生成坐标,产出 pyautogui 代码gui_agents/s3/agents/grounding.py
定位模型 (UI-TARS)输入"描述 + 截图",输出一个点的 (x,y)经 generate_coords 调用,grounding.py:230
CodeAgent嵌套子 agent:纯代码就能干的任务(表格计算等)交给它跑gui_agents/s3/agents/code_agent.py
PROCEDURAL_MEMORY所有系统提示词的集中地(Worker / 反思 / Code / 评委)gui_agents/s3/memory/procedural_memory.py
Behavior Best-of-N离线:对同一任务的多次 rollout,先给每步配字幕、再让评委挑最优gui_agents/s3/bbon/ + osworld_setup/s3/bbon/

主线走一遍(高层,不进代码):

  1. 截图 + 任务 → 喂给 Worker.generate_next_action(worker.py:178)。
  2. 大脑模型先(可选)收一段"反思",再产出一段自然语言推理 + 一行动作代码,例如 agent.click("右上角的保存按钮")。
  3. 这行代码里的"右上角的保存按钮"还是文字。create_pyautogui_code(common_utils.py:15)用 eval 执行它,触发 OSWorldACI.click,后者调用定位模型把描述变成 (x,y),拼成真正的 pyautogui.click(x, y) 字符串。
  4. CLI 的 run_agent 拿到这串字符串,exec() 在真机上落地(cli_app.py:215)。
  5. 下一轮新截图进来,直到模型给出 agent.done() 或步数耗尽。

一个关键的认知:S3 是"扁平"的。 它的前代 S2 有一个 Manager,会先把大任务规划成 DAG(有向无环图)子任务、还查知识库和网络。S3 故意删掉了整个层级规划(见 04 章对比),用"一个 Worker 一路走到底 + 离线 Best-of-N"换取更简单、更快、更强。这是理解整个项目最重要的一条主线。

阅读地图(建议顺序)​

章节讲什么适合
01-architecture.md两段式架构全景:为什么要拆"大脑"和"定位";S1→S2→S3 的演化主线想先看懂"大盘"
02-grounding-aci.mdACI 是什么、@agent_action 怎么把方法变成可调 API、英文描述如何落到 (x,y)、文本定位走 OCR想懂"手脚怎么精确落点"
03-worker-loop.mdWorker 单步循环、Reflection 反思 agent、长上下文图片裁剪、格式校验重试想懂"大脑每一步在干嘛"
04-code-agent-and-bbon.md嵌套 Code Agent(代码执行子 agent)、Behavior Best-of-N 测试期投票、与 S2 的横向对比想懂 S3 的两个杀手锏

代码地图(导航索引)​

主题文件路径符号名
顶层 agentgui_agents/s3/agents/agent_s.pyAgentS3 / UIAgent
Worker 主循环gui_agents/s3/agents/worker.pyWorker.generate_next_action
动作接口 / 定位gui_agents/s3/agents/grounding.pyOSWorldACI / generate_coords / agent_action
嵌套代码 agentgui_agents/s3/agents/code_agent.pyCodeAgent.execute
所有系统提示词gui_agents/s3/memory/procedural_memory.pyPROCEDURAL_MEMORY
行为字幕(BBoN)gui_agents/s3/bbon/behavior_narrator.pyBehaviorNarrator.judge
比较评委(BBoN)gui_agents/s3/bbon/comparative_judge.pyComparativeJudge.judge
CLI 主驱动gui_agents/s3/cli_app.pyrun_agent / main
LLM 多后端封装gui_agents/s3/core/mllm.pyLMMAgent