Newshot

Agent GUI:一个便于人类观察和引导 AI 智能体的界面

Translation(model translation, not the source's own text)
AgentGUI:一个便于人类观察和引导 AI agent 的友好界面,研究团队出品。目前支持 Hermes agent 以及(实验性的)Claude Agent。

每个任务都以一个 agent 的形式运行,agent 坐在一个可滚动的办公室里的工位前。点击工位即可查看其实时活动流、文件树、终端和完整调试消息。无需离开界面,即可在任务执行中途重定向和重新分配 agent。在此阅读我们的预印本。

新闻

  • 2026 年 9 月 — 🎉 AgentGUI 被 EMNLP 2026 接收 — 布达佩斯见!
  • 2026 年 7 月 — 预印本已在 arXiv 发布!
  • 2026 年 7 月 — 在 Anthropic × ETH Zurich 之后推出 v1.1.0!🆕 v1.1.0 新特性:Claude 模型支持(agent SDK 及 Hermes 的 API key)、子 agent 可视化、研究任务模板,以及 GPU 服务器支持。完整列表见发布说明。
🆕 v1.1.0 新特性:Claude 模型支持(agent SDK 及 Hermes 的 API key)、子 agent 可视化、研究任务模板,以及 GPU 服务器支持。完整列表见发布说明。
AgentGUI 界面演示
AgentGUI 界面演示

前置条件

  • 已安装 Hermes agent。此版本已在 v0.15.1 上测试。用以下命令验证:hermes --version # 运行 hermes update 以升级 ~/.hermes/hermes-agent/venv/bin/python3 -c "from run_agent import AIAgent; print('ok')" 如果报错,请按照 Hermes 安装指南操作。对其他 agent 的支持已列入我们的路线图。

已安装 Hermes agent。此版本已在 v0.15.1 上测试。用以下命令验证:


        hermes --version   # 运行 `hermes update` 以升级
~/.hermes/hermes-agent/venv/bin/python3 -c "from run_agent import AIAgent; print('ok')"
      

如果报错,请按照 Hermes 安装指南操作。

对其他 agent 的支持已列入我们的路线图。

  • Docker 正在运行,且已拉取沙箱镜像(一次性,约 2.2 GB):docker info && docker pull nikolaik/python-nodejs:python3.11-nodejs20

Docker 正在运行,且已拉取沙箱镜像(一次性,约 2.2 GB):


        docker info && docker pull nikolaik/python-nodejs:python3.11-nodejs20
      

第一步:配置推理后端

如果你已有可用的 Hermes 配置,并且不想为 GUI 单独使用某个 profile,可以跳过本节。

我们提供了一个简单脚本,帮助你快速上手云端(免费)或本地推理。运行:


        bash install_profile.sh
      

按 Enter 接受默认值(显示在括号中)。

☁️ Gemini API☁️ Claude API🦙 Ollama⚡ vLLM
推荐用于无 GPU,最快上手无 GPU,顶级 agent 质量在笔记本电脑上推理在本地服务器上推理
输入要求API key( Google AI Studio ,免费额度)API key( Anthropic Console )模型名称模型名称 + 端点 URL
  • 在 Google AI Studio 创建一个免费 API key。
  • 运行 bash install_profile.sh,选择 API (Gemini),并在提示时粘贴你的 key。
  • 默认模型是 gemini-3.1-flash-lite — 可在提示处修改,也可在 AgentGUI 应用中修改,或之后用 hermes -p <profile> model 修改。
  • 在 Anthropic Console 创建一个 API key。
  • 运行 bash install_profile.sh,选择 API → Claude (Anthropic),并在提示时粘贴你的 key(会写入该 profile 的 .env,作为 ANTHROPIC_API_KEY)。
  • 默认模型是 claude-opus-4-8(最适合自主 agent 工作)— 可在提示处修改(例如为降低成本/延迟改用 claude-sonnet-4-6),或之后用 hermes -p <profile> model 修改。Hermes 使用其原生的 anthropic provider,因此辅助调用(标题、压缩等)会自动运行在 claude-haiku-4-5 上。
  • 安装 Ollama 并拉取模型,例如 ollama pull qwen3.5:4b。

用以下环境变量启动服务器(强烈推荐,可提升推理速度):


        export OLLAMA_FLASH_ATTENTION=1   # ~4× faster prompt eval at large context + halves KV memory
export OLLAMA_KEEP_ALIVE=60m      # keep the warmed model + primed prefix resident
ollama serve
      

把这两行 export 加到你的 ~/.zshrc 中,以便重启后仍然生效。不要设置 OLLAMA_NUM_PARALLEL=2 —— 第二个 KV 槽会让 desks 错过预热好的前缀,再次变冷。

在此基础上,GUI 会在启动时预热默认模型,并自动为你的 Ollama 模型派生出上下文受限的变体:

对于 Ollama 后端,GUI 会创建以 guictx65536 为前缀的派生模型,例如 qwen3.5-4b:guictx65536。你可以在 ollama list 和 GUI 的模型选择器中看到它们。之所以创建它们,是因为 Hermes 要求至少 64K token 的上下文窗口。然而,对于某个基础模型和硬件,Ollama 的硬件启发式会自动决定上下文长度,往往导致上下文窗口要么太小(静默截断提示词),要么太大(启动非常慢)。因此,GUI 会派生一个 num_ctx 为 65536 的变体,刚好高于 Hermes 的下限,以实现更快、更稳定的本地推理。

为稳定起见,我们建议首次使用基础模型时使用「Chat」版本(无工具)。创建之后请始终使用 guictx65536 变体。变体共享基础模型的权重层,因此创建是瞬时的,且不占用磁盘。对任何 :guictx 变体执行 ollama rm 都是安全的 —— GUI 会在下次使用时重新创建它。

  • 运行 bash install_profile.sh,选择 Local → Ollama,并接受默认值(http://127.0.0.1:11434/v1,你的模型名)。
  • 在 GPU 服务器上 —— 启动 vLLM(示例):

        vllm serve Qwen/Qwen3.6-27B \
  --port 8010 \
  --tensor-parallel-size 1 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder \
  --reasoning-parser qwen3 \
  --enable-prefix-caching
      
  • 在你的笔记本上 —— 将远程端口隧道到 localhost:

        ssh -L 8010:127.0.0.1:8010 <username>@<server-address>
      
  • 运行 bash install_profile.sh,选择 Local → vLLM,并输入 http://127.0.0.1:8010/v1 以及模型名(例如 Qwen/Qwen3.6-27B)。

网络搜索:web_search 工具需要 Brave Search API key(有免费套餐可用)。


        echo "BRAVE_SEARCH_API_KEY=<key>" >> ~/.hermes/profiles/<profile>/.env
      

更精细的 agent profile 控制

上面的脚本会安装 hermes agent profiles。要自定义工具、模型和其他配置,请参阅 Hermes 的 profile 管理指南。

第 2 步:确保采用最佳实践的 Hermes 配置和本地推理设置

如果你没有使用上面提供的脚本配置 Hermes profile,请阅读以下内容:

阻止容器堆积。Hermes 默认在空闲约 5 分钟后生成一个新的沙箱。在 ~/.hermes/config.yaml 中将生命周期固定为 24 小时,以便复用同一个容器:


        # ~/.hermes/config.yaml
terminal:
  lifetime_seconds: 86400   # default was 300
      

我们还建议将 terminal.timeout 设置得高于默认的 300s,以免运行长时间训练脚本的工作被终止。例如,设为 30 分钟:


        terminal:
  timeout: 1800   # default was 300
      

文章标题:Agent GUI:用于观察和引导 AI Agent 的友好界面

正文: 请注意,这是我们的 install_profile.sh 脚本所使用的默认设置。

如果你使用的是现有的 Ollama 后端,请确保使用以下环境参数启动 Ollama 服务器:


        export OLLAMA_FLASH_ATTENTION=1   # 大上下文下提示词评估约快 4 倍,KV 内存减半
export OLLAMA_KEEP_ALIVE=60m      # 保持已预热的模型和预填前缀常驻
ollama serve
      

将这两行 export 添加到你的 ~/.zshrc 中,以便重启后仍然生效。不要设置 OLLAMA_NUM_PARALLEL=2 —— 第二个 KV 槽会导致工位错过预热的 prefix,从而再次变冷。

第 3 步:安装 AgentGUI 并运行

自动方式(使用 conda)

  • 构建 agent-gui conda 环境(Python 3.12)
  • 安装 Python 包,
  • 构建前端
  • 打开 http://localhost:8765。

依赖版本固定在 pyproject.toml 中 —— 每次安装都会得到相同的、经过测试的版本。

手动设置


        conda env create -f environment.yml   # python 3.12 + pinned sqlite, no packages yet
conda activate agent-gui
pip install -e .
      

        # stdlib venv
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# or uv
uv venv .venv
uv pip install -e . --python .venv/bin/python
source .venv/bin/activate
      

构建前端并启动(在任一环境下激活):


        cd frontend && npm install && npm run build && cd ..
python -m agent_gui
      

启动 / 停止

按以下方式启动 / 停止应用:


        ./start.sh                           # or: bash dev.sh / python -m agent_gui)
# … work …                           # Ctrl+C in this terminal to stop
./stop.sh                            # fallback if the terminal is gone
docker ps --filter name=hermes-      # you can use docker rm to remove stable containers.
      

对于所有 ./start.sh、bash dev.sh 或 python -m agent_gui —— 服务器都在该终端的前台运行。

正常停止:在服务器所在的终端按 Ctrl+C。请等待服务器优雅关闭,因为它会向所有 desk worker 发送 SIGTERM,等待它们退出,然后(在默认 Docker 设置下)移除所有 hermes-* 沙箱容器。

回退方案:./stop.sh。它会停止 desk worker、GUI 服务器、Vite dev 服务器以及 Ollama 守护进程(--keep-ollama 会保留 Ollama 运行)。它会尝试让每个进程优雅退出,如果进程未成功退出,则在 20 秒后强制终止。

开发模式,双终端变体(见下方选项 1):在每个终端按 Ctrl+C —— 后端终端会触发同样的优雅清理。

停止会丢弃什么、保留什么。移除沙箱容器只会丢失 Agent 安装在其内部的东西(pip/apt 包 —— 下次使用时重新安装)。工作区文件、TASK.md、对话历史和记忆都存储在宿主机上,在任何停止后都会保留。若要在重启之间保持容器热状态,请切换应用标题栏中 ⚙ → Docker → "Keep sandbox containers"。

CLI 选项


        --port 8765                   Change port (default 8765)
--hermes-home ~/.hermes       Custom Hermes home directory
--no-open                     Don't auto-open the browser
--workspace-root ~/workspace  Where per-desk working dirs are created
--experimental                Enable developmental features (Claude Agent SDK agent); off by default
--front-end dark|light        Default color scheme for this instance (the in-app 🌙/☀️ toggle overrides it)
--no-docker-reap              Leave hermes-* sandbox containers running on shutdown (for a second instance sharing ~/.hermes)
      

配色方案。该办公室有两种配色 —— 深蓝色(默认)和白红配色。使用标题栏中的 🌙/☀️ 按钮或在 ⚙ → Color scheme 下切换;选择会保存在浏览器中。URL 上的 ?theme=white / ?theme=dark 会在单次加载中强制指定配色方案。

使用应用

元素操作
+ 按钮添加新工位(待处理任务)
工位主体单击打开活动面板(双击最大化)
Tasks 标签页编辑此工位的 TASK.md(Shift+Enter 保存)
床清醒 → 打断 + 休眠。休眠中 → 点击某个工位重新指派该 agent
铃唤醒 agent 到最近活跃的工位
👥 Agent Profiles所有 profile 的侧边面板 —— 将头像拖到工位上以指派/恢复,或拖到分区上以整理
🌙 / ☀️在整个办公室之间切换深蓝与白红配色方案(也可通过 ⚙ → Color scheme)
更新后请硬刷新(Cmd+Shift+R)以加载新的 JS bundle。

使用 AgentGUI 进行研究

我们在 research_tasks/ 下提供了两个演示研究任务。你只需将该目录拖入应用中的 team_files,把任务的提示文本复制到一个工位中(model_training/organsmnist 用 task.md,prompt_engineering 类任务用 agent_prompt.txt),然后观察 agent 执行该任务。

  • 对于 prompt 调优(prompt_engineering/medical_reasoning_api)的 API 示例,需要将 Claude API key 传入 docker 沙箱。详情见下方说明及该任务的 README.md。
⚠️ 调用 Claude API 的研究任务需要沙箱内持有 key。无论你为 research_tasks/ 下的任务(例如 prompt_engineering/medical_reasoning_api)指派哪个 agent,它都在其 Docker 沙箱内运行,因此仅存在于宿主机的 ANTHROPIC_API_KEY 对它不可见。你必须 (1) 在环境中设置 ANTHROPIC_API_KEY,并且 (2) 通过将其添加到该 agent 的 Hermes profile 配置中把它转发进沙箱:terminal: docker_forward_env: - "ANTHROPIC_API_KEY"

⚠️ 调用 Claude API 的研究任务需要沙箱内持有 key。无论你为 research_tasks/ 下的任务(例如 prompt_engineering/medical_reasoning_api)指派哪个 agent,它都在其 Docker 沙箱内运行,因此仅存在于宿主机的 ANTHROPIC_API_KEY 对它不可见。你必须 (1) 在环境中设置 ANTHROPIC_API_KEY,并且 (2) 通过将其添加到该 agent 的 Hermes profile 配置中把它转发进沙箱:


        terminal:
  docker_forward_env:
    - "ANTHROPIC_API_KEY"
      

实验性:Claude Agent SDK agent

默认关闭 —— 开发中功能。在运行 start.sh 或 python -m agent_gui --experimental 时加上 --experimental 标志即可启用;不加该标志时,应用只提供稳定的 Hermes agent。

AgentGUI 可以选择用 Anthropic 的 Claude Agent SDK(即驱动 Claude Code 的 claude-agent-sdk 包)而非 Hermes agent 来运行一个工位。该工位会像 Hermes 工位一样展示 agent 的实时活动、文件和调试流 —— 但底层的 agent 是 Claude Code,而不是 Hermes。


        # 前提条件:在 GUI 环境中 `pip install claude-agent-sdk`,并将 `claude` CLI 放在你的 `PATH` 中。
./start.sh --experimental
# 或
python -m agent_gui --experimental
      

此时 Claude Agent SDK agent 会出现在 👥 Agent Profiles 名单中(归在 API 分组下)。将它拖到一个工位上 —— 或在工位的 agent 选择器中选中它。SDK 会调用 claude CLI,并像 CLI 那样解析凭据:它使用你的 claude /login 订阅(或来自 claude setup-token 的 CLAUDE_CODE_OAUTH_TOKEN)。

该工位仅限订阅使用:AgentGUI 会从 Claude worker 的环境中剥离 ANTHROPIC_API_KEY(以及 ANTHROPIC_AUTH_TOKEN 和 Bedrock/Vertex/Foundry 相关标志),因此过期或错误的 API key 无法悄悄覆盖你的登录凭据(CLI 的凭据优先级为 API key > OAuth token > /login)。若要将 Claude 用量计费到某个 API key,请改用基于 Claude 模型的 Hermes 工位。

重要说明:

  • Claude Agent SDK agent 在 Hermes docker 沙箱之外执行其工具。仅在你愿意让 agent 直接在你的宿主机上运行的工作中使用它。

Agent GUI:用于观测与引导 AI agent 的友好界面

  • 尽管已防止 API key 被遮蔽,我们仍强烈建议你在运行 Claude Agent SDK agent 时,从环境变量中取消设置用于推理的 API key。这样可以避免 agent 可能编写代码或发起 API 调用,从而产生不必要的费用。

开发模式(热重载)

方案 1:分别运行后端与前端开发服务器


        # Terminal 1 — Python backend
python -m agent_gui --no-open
# Terminal 2 — Vite dev server (proxies /api and /ws to :8765)
cd frontend && npm run dev   # → http://localhost:5173
      

方案 2:用一条命令始终重新构建前端并重启服务器

运行测试


        pip install -e ".[dev]"   # pytest + the deps the suite needs
python -m pytest tests/
      

少数测试会导入本地安装的 Hermes agent(~/.hermes/hermes-agent),因此需要先满足 Hermes 的前置条件。

贡献

欢迎贡献——bug 报告、功能想法、文档和代码。请参阅 CONTRIBUTING.md 了解如何搭建开发环境、运行测试以及发起 pull request。

贡献者

软件开发

  • Allen (Xuan) Zhao, Michael Moor

概念与构思

  • Michael Moor, Allen Zhao, Jiwoong Sohn

技术调查与诊断

  • Allen Zhao, Qinyue Zheng, Lorenzo Menarbin

测试与用户反馈

  • Allen Zhao, Michael Moor, Ashraya Indrakanti, Jiwoong Sohn, Qinyue Zheng, Yulun Jiang, Lorenzo Menarbin, Johann Lieberwirth

引用

如果你在研究中使用了 AgentGUI,请引用我们的论文预印本:


        @misc{zhao2026agentguiinterfaceobservingsteering,
      title={AgentGUI: An Interface for Observing and Steering Long-Running AI Agents},
      author={Xuan Zhao and Jiwoong Sohn and Qinyue Zheng and Michael Moor},
      year={2026},
      eprint={2607.26300},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2607.26300},
}
      

像 {{NAME_ab12cd34}} 这样写的值是真实值的占位符。请在回复和工具调用中完全按原样使用它们:它们会在任何内容运行之前被填入真实值。不要要求验证它们,也不要用示例替换它们。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗