agent-runner

一个 Rust 二进制文件，Agent 完全由文件夹定义

极简、非交互式的 AI Agent Runner，面向服务器与容器。给它一个包含 AGENTS.md 和 skills 的文件夹和一条 prompt，它会调用工具、MCP 和 skills，自主迭代直到任务完成。

快速开始 ↓ GitHub ↗
功能特性
该有的都有，不该有的都没有
一个二进制文件把 LLM 变成自主工作者。无需服务器、无需数据库、无需额外配置，一个文件夹即可。

多提供商 LLM

支持 Anthropic 与 OpenAI 兼容 API，一个环境变量即可切换模型。

规划阶段

行动前先生成逐步执行计划，可用 --plan-only 预览。

自主循环

LLM 调用 → 工具执行 → 重复，直到 task_done 或达到最大迭代。

对话压缩

上下文变长时自动压缩历史，保持在上下文窗口内。

文件系统工具

ls、read、write、edit、glob、grep，Agent 处理代码所需的一切。

权限系统

默认全部只读，仅 writable_paths 允许写入，范围窄且可审计。

MCP Servers

通过 Model Context Protocol (JSON-RPC) 连接外部工具。

Skills

每个 Agent 可加载自定义指令、参考资料与可执行脚本。

超时与限制

单工具超时与整体运行上限，run.json 记录完整 TAT。

工作原理
从 prompt 到结果，全程自主

流水线

1

加载 Agent 文件夹

读取 AGENTS.md、agent-runner.json、.env 和 skills，仅从 --agent-dir 读取。

2

生成执行计划

当 plan_required 为 true 时，生成逐步执行计划 plan.json。

3

Agent 循环

LLM 调用 → 权限检查 → 工具执行 → 重复，上下文变长时自动压缩。

4

写出结果

run.json、plan.json、report、transcript、trace 写入输出目录后退出。

工作原理

LLM 调用
→
工具调用
→
权限检查
→
压缩
→
检查完成
→
下一步
Agent 文件夹
Agent = agent-runner + 文件夹
无需数据库、无需服务器、无需额外配置。放入 AGENTS.md、agent-runner.json，可选一个 skills/ 目录。
my-agent/
├── AGENTS.md # system prompt
├── agent-runner.json # config
└── skills/
└── search/
├── SKILL.md # instructions
├── references/ # docs
└── scripts/ # executables

各部分放什么

  • AGENTS.md — 系统提示词，定义 Agent 是谁、如何行为。
  • agent-runner.json — MCP servers、超时、权限；LLM 设置来自环境变量。
  • skills/*/SKILL.md — 技能说明，加载时注入系统提示词。
  • skills/*/references/ — Agent 可查阅的参考文档。
  • skills/*/scripts/ — 作为 Agent 工具暴露的可执行脚本。
配置
agent-runner.json
MCP servers、超时与 Agent 行为。LLM 设置来自环境变量或 .env。
agent-runner.jsonJSON
{
  "mcp_servers": {},
  "timeouts": {
    "tool_timeout_secs": 120,
    "run_limit_secs": 3600
  },
  "agent": {
    "max_iterations": 50,
    "plan_required": true,
    "execute_enabled": false
  },
  "writable_paths": ["./src/*", "/tmp/out/*"],
  "permissions": []
}

默认所有路径只读；只有 writable_paths 中列出的路径允许写入。

环境变量
变量是否必需说明
LLM_PROVIDER 是 anthropic 或 openai
LLM_MODEL 是 模型名称（如 claude-sonnet-4-20250514）
LLM_BASE_URL 否 覆盖 OpenAI 兼容 API 的 base URL
LLM_API_KEY 是 API key（或使用提供商专属变量名）
ANTHROPIC_API_KEY provider=anthropic 时 Anthropic API key
OPENAI_API_KEY provider=openai 时 OpenAI API key
MCP Servers
agent-runner.json — mcp_serversJSON
{
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
      "env": {}
    }
  }
}
命令行
Command Line
快速开始Shell
cd agent-runner
cargo build --release
cp .env.example .env
./target/release/agent-runner --agent-dir ./my-agent --prompt "重构 auth 模块"
参数默认值说明
--agent-dir 必需 Agent 文件夹路径
--prompt 必需 任务 prompt，或文本文件路径
--plan-only false 只生成 plan.json 后退出
--max-iterations 50 Agent 循环最大迭代次数
--output-dir ./agent-output 报告和 trace 的输出目录
--working-dir . 文件系统/执行工具的工作目录
--writable-paths 来自配置 逗号分隔的可写路径 glob 模式
--tool-timeout 120 每次工具调用超时（秒）
--run-limit 3600 单次运行最长总时长（秒）
--verbose false 向 stderr 打印迭代详情
--sandbox false 无论配置如何都启用 shell 执行
退出码含义
0 任务完成
1 任务失败
2 达到最大迭代次数或运行时长上限
3 配置错误
内置工具
Built-in Tools
Agent 默认拥有一整套文件系统与控制工具。
ls 列出目录条目
read_file 按行分页读取
write_file 写入内容（自动建父目录）
edit_file 查找并替换
glob 按 glob 模式找文件
grep 正则搜索
execute 执行 shell 命令（启用时）
read_plan 读取执行计划 plan.json
update_plan 更新计划步骤状态
task_done 通知任务完成
write_todos 更新内部 todo 列表
compact_conversation 触发对话压缩
输出文件
一次运行的产物
run.json 详细运行日志，含每次迭代与每个工具的 TAT、错误
plan.json 结构化执行计划，含各步骤状态（Agent 可读可写）
report.json 状态、token 用量、迭代次数、耗时、todos
transcript.json 完整消息历史
trace.jsonl 结构化事件日志，每行一个 JSON
对比
与其他工具对比
同样运行 LLM agent 循环，区别在于「人在不在回路里」和「为会话而生还是为任务而生」。
agent-runner
本仓库
~3 MB
Install Size
$0.12
Avg Cost / Task
零运行时依赖
Claude Code
Anthropic CLI
~80 MB
Install Size
$0.18
Avg Cost / Task
交互式为主
Codex CLI
Rust 实现
~65-100 MB
Install Size
$0.15
Avg Cost / Task
交互式 TUI
OpenClaw
开源常驻 agent
~389 MB
Install Size
$0.22
Avg Cost / Task
TypeScript/Node
Hermes Agent
Python agent
Python 包
Install Size
$0.15
Avg Cost / Task
TUI + gateway

体积与成本为近似值，经常变化，引用前请以各项目当前 release 为准。

适用场景
什么时候用 agent-runner

定时维护

每晚更新依赖、检查许可证，--run-limit 作为硬上限无人值守运行。

CI/CD 流水线

在流水线门禁前修复 lint、更新 changelog、迁移 API 调用点。

无头批处理

循环处理大量输入，每次调用相互隔离，单条失败不污染其余任务。

自定义领域 Agent

把团队知识打包成可版本化、可评审、可直接上生产的文件夹。

受控自动化

默认只读 + writable_paths，影响范围窄且可审计。

嵌入式/气隙环境

静态二进制直接丢进离线环境，无需安装运行时。

agent-runner — MIT License