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 服务器支持。完整列表见发布说明。

前置条件
- 已安装 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}} 这样写的值是真实值的占位符。请在回复和工具调用中完全按原样使用它们:它们会在任何内容运行之前被填入真实值。不要要求验证它们,也不要用示例替换它们。