ApodexAI/FrontierAgent · 上手攻略
- 仓库：ApodexAI/FrontierAgent
- 链接：https://github.com/ApodexAI/FrontierAgent
- 分类：AI Agent Framework
- 作者：Tom
- 更新：2026-08-27
是什么
FrontierAgent 是 ApodexAI 开源的一个agent 运行时 + 终端产品 + 评测套件三位一体项目，定位是"长程研究代理和基于文件工作的完整解决方案"。核心由三层组成：
- TUI 终端：交互式命令界面，支持实时任务面板、审批流、异步干预。
- Workflow 引擎：两种内置工作流——
ReAct（单 agent 状态机）和Agent Team（协调者 + 并行子 agent）。 - 评测层：内置
FrontierSearchBench/FrontierChallenge等 benchmark，支持研究类和文件类任务的自动评测。
配套 Apodex 商业平台（API Key 接入），也支持自托管 SGLang 模型。
解决什么问题
长程 agent 任务长期面临几个痛点：
- 缺乏结构化并行：传统 ReAct agent 顺序执行，多任务场景效率低。
- 文件操作风险：agent 在真实目录中写入文件，缺乏沙箱保护。
- 缺乏可复现评测：自研 agent 缺乏标准 benchmark，只能靠"体感"。
- 运营不透明：任务进度、审批状态、子 agent 产出缺乏实时可见性。
FrontierAgent 用 Task Board（任务看板）+ 沙箱文件系统 + 内置评测三件套解决。
快速安装
环境要求
- Git
- Python 3.12
uv（Astral 出品的 Python 包管理器）- OpenAI 兼容模型端点（自托管或商业 API）
- Docker（可选，用于容器化运行）
基础安装（托管端点，macOS / Linux）
git clone https://github.com/ApodexAI/FrontierAgent.git
cd FrontierAgent
uv sync --python 3.12 --extra dev
cp .env.example .env
编辑 .env 填入：
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1
OPENAI_MODEL=your-model-name
# 可选：网页研究工具
SERPER_API_KEY=
JINA_API_KEY=
启动 TUI：
# 单 Agent ReAct 模式
uv run frontier-agent --mode react --cwd /path/to/project
# Agent Team 协调者模式
uv run frontier-agent --mode agent_team --cwd /path/to/project
⚠️ SGLang 本地服务版本与驱动/CUDA 版本强绑定，出现 Triton kernel 错误时请对照 GPU compatibility matrix 核验驱动版本。
懒人脚本（macOS / Linux）
# macOS
./scripts/run-macos.sh
# Linux（仅端点）
./scripts/run-linux.sh
# Linux + 本地 SGLang GPU（需 NVIDIA）
./scripts/run-linux-gpu.sh --install-system-deps --setup-only
Docker 方式
# 克隆后
cd FrontierAgent
docker compose up
核心用法
ReAct 模式（单 Agent 状态机）
适合：单项目研究、文档撰写、代码修改。
uv run frontier-agent --mode react --cwd ./my-project
- agent 在任务范围内读写文件，迭代交付产出物。
/inputs只读，/workspace可写，/outputs存放最终交付物。- 写操作会弹出 diff 审批界面，可加
--yes跳过。
Agent Team 模式（协调者 + 并行子 Agent）
适合：多方向并行调研、多模块并行开发。
uv run frontier-agent --mode agent_team --cwd ./my-project
- 协调者接收任务 → 拆解子任务 → 分派给并行子 agent。
- TUI 侧边栏实时显示 Task Board（pending / active / completed / blocked / cancelled）。
- 可选 fast reporter 做最终证据复核。
- 运行时输入会进入指令队列，下一个安全边界注入，不中断正在运行的 sub-agent。
评测模式
# 安装评测依赖
uv sync --python 3.12 --extra dev
# 运行评测
uv run frontier-agent eval --benchmark frontier_search_bench
⚠️ 评测结果需要配置 judge 模型，未配置时评测层不会自动运行。详见 eval.md。
常用命令行参数
| 参数 | 说明 |
|---|---|
--mode react\|agent_team |
选择工作流模式 |
--cwd <path> |
任务根目录 |
--yes |
跳过所有审批确认 |
--resume |
恢复已保存的运行 |
uv run frontier-agent --help |
查看完整参数列表 |
会话恢复
uv run frontier-agent --resume
# 或在 TUI 内
/revert # 恢复 session 变更
典型适用场景
- 多方向并行调研：产品调研 + 技术评估 + 竞品分析同时跑。
- 代码库研究：不了解的大型 repo，用 agent 读文件、做分析、写报告。
- 评测自己的 agent：用 FrontierAgent 内置 harness 跑自己的 agent，量化性能。
- 沙箱文件操作：不确定 agent 会产生什么副作用，先在沙箱里跑一遍。
坑与注意
- SGLang 版本与 CUDA 驱动不匹配：这是项目文档明确警告的坑。Triton kernel 报错通常意味着版本错配，对照 gpu-compatibility.md 核验。
- Docker 模式下
/outputs映射：macOS/Docker 下outputs 映射到宿主机的.apodex/runs/<run-id>/outputs，首次使用建议确认路径存在。 - Agent Team 干预是异步的：运行时输入的指令不会立即生效，要等当前 sub-agent 到达安全边界才会注入。
- 评测层需单独配置 judge：默认安装不包含评测运行，仅安装 harness。
- Python 3.12 强依赖：其他 Python 版本未测试，使用 3.11 或 3.13 可能遇到兼容问题。
与同类对比
| 维度 | FrontierAgent | OpenClaw | LangChain Agents | CrewAI |
|---|---|---|---|---|
| 工作流模式 | ReAct + Agent Team | 多协议 agent | LCEL AgentExecutor | Crew → Agents |
| 评测内置 | ✅ 完整 harness | ❌ | ❌ | ❌ |
| 沙箱文件 | ✅ 任务级沙箱 | ❌ | ❌ | ❌ |
| TUI | ✅ 交互式 TUI | ✅ | ❌ | ❌ |
| 商业配套 | Apodex API | OpenClaw Cloud | LangSmith | ✖ |
| 开源协议 | MIT | Apache 2.0 | MIT | MIT |
核心差异化：FrontierAgent 把评测层和沙箱层做成框架内置能力，而不只是 agent 执行引擎。对于需要"开发 → 评测 → 迭代"闭环的团队，这点是其他框架不具备的。
一句话推荐结论
如果你需要一个同时能做 agent 执行、沙箱验证、量化评测的完整工作台，FrontierAgent 是目前开源领域最接近这个目标的项目，尤其适合研究型团队和 agent 开发者。
来源：GitHub README · docs/README.md · Tech Blog (apodex.com) · Tech Report (arXiv 2608.23283) · tui-endpoint-quickstart.md · tui-user-guide.md · eval.md · gpu-compatibility.md