AgentRun 开源发布：为智能体加上自改进与持久化执行

运行更智能的智能体。使用更少的 token。

今年我们的代码审查账单涨了 36 倍。现在一次审查只花我们 18 美分。看看怎么做 ↓

快速开始 · 案例研究 · 导览 · 模板 · 部署 · 文档

AgentRun 是一个开源平台，能为你的智能体强力加速。它在您喜爱的智能体运行框架之上，增加了自我改进、持久化执行和一个控制平面。你的智能体变得更聪明、更容错，并且每次运行都使用更少的 token。

_{某个智能体的“学习”标签页：它保留了什么，以及此后发生了什么变化。演示数据来自控制台录制的测试夹具。}

案例研究

代码审查。Greptile 从三月起每次审查收费一美元，随后我们的智能体起飞了，账单从每月 180 美元涨到 6,451 美元。于是我们在一个廉价模型上构建了自己的审查器，并用我们自己的 PR 对它进行调优。每次审查成本 18 美分，在 30 个它从未见过的 PR 上，它发现的真实 bug 是 Greptile 的 1.6 倍。我们是如何构建的 · 在你的仓库上调优一个

商户代码。我们让 Opus 弄清楚如何对商户进行分类，然后把它学到的东西交给一个廉价模型。同样的工作，每个商户从 0.89 美元降到 0.12 美元。工作原理 · 用你自己的任务来做

为什么选择 AgentRun

智能体非常擅长弄清楚事情。问题在于它们会一遍又一遍地弄清楚同样的事情。给一个智能体一项它已经做过上百次的任务，它会重新发现同样的 API、重读同样的文档、重建同样的计划，而你要为其中的每一个 token 付费。

把你最好的智能体带到它运行最佳的框架上：Claude Code、Codex、OpenCode 或 pi。AgentRun 负责它周围的一切：

• 它会学习工作。每次运行后，智能体会保留对下次有帮助的内容：一条笔记、一项技能，或一个无需循环即可完成该任务的工作流。下一次运行就从那里开始。
• 它从不丢失运行。每次运行都存在于一个存储中。在运行中途杀掉服务器，再重新启动，运行会继续。给每个智能体提供任务所需的计算机：沙箱、Linux 桌面、Android 手机或浏览器。
• 你始终掌控全局。审批、支出上限，以及每个智能体的统一控制台：什么需要你处理、什么失败了、什么正在运行，以及花费了多少。

你无需构建底层管道：提供商集成、恢复、运行跟踪和学习都在这里。用一条命令在你的笔记本电脑上运行它，或在一个容器中运行，或作为带运行器的服务器运行。Apache-2.0。

三步开始

你需要 Node 24.22.3 或更新版本，运行在 macOS 或 Linux 上。

1. 启动它。

   npx @parcha/agentrun

   它会启动服务器和一个运行器，端口为 7340（或下一个空闲端口），将所有内容保存在 ~/.agentrun 中，并在浏览器中打开控制台。

2. 添加一个模型密钥。在控制台中设置密码，然后在设置 → 模型密钥下添加一个密钥。一个 OPENROUTER_API_KEY 就能为每个框架提供模型。Anthropic 密钥可运行 pi 和 Claude Code；OpenAI 密钥可运行 pi、Codex 和 OpenCode。

3. 运行你的第一个智能体。打开模板，应用KYB 尽职调查，然后用一家公司的名称和网站启动一次运行。它只需要你的模型密钥。完成后，运行的报告标签页会有一份尽职调查报告，包含结论和每项主张的引用。然后打开该智能体的学习标签页，看看它为下次保留了什么。

更想让你的编码智能体来做？告诉它：Read agentrun.ai/SKILL.md and set up AgentRun for me。

Docker、沙箱以及在服务器上运行它

如果你的机器上运行着 Docker，新智能体会获得一个带 shell 的 Docker 沙箱。它的镜像在首次使用时构建，需要几分钟，控制台会在就绪时提示。没有 Docker 时，智能体仍可读写文件，但没有 shell。

想要一个带 URL 的自己的服务器？一键部署到 Render。

开始导览

做出判断的工作流。 一个步骤可以提出一个快速的类型化问题，查看答案有多确定，并选择一条路径。这里模型倾向于批准，置信度为 0.61，低于工作流 0.75 的门槛，因此该案例进入审核。

所有智能体集中一处。 首先打开 Mission Control：哪些需要你处理、哪些失败了、哪些正在运行以及花费多少，按天、按 harness 和按工具查看。

每个智能体都是一个 API。 从 Playground 启动一次运行，然后把同样的请求复制到你的代码中。

你始终掌控全局。 智能体可以停下来问你，运行会等待你的回答。

会学习工作的智能体

在智能体的定义中用 "learning": true 开启它。每次运行结束时，智能体会多获得一轮机会，说出它想保留的内容。AgentRun 会检查、评分，并把保留项提交到智能体自己的 git 文件夹。下一次运行就从那里开始。

flowchart LR
    start["Run starts from<br/>the agent's main"] --> work["Run does the job"]
    work --> propose["Last turn proposes<br/>notes, a skill, a workflow"]
    propose --> check["Code checks,<br/>then one grader"]
    check -->|kept| commit["Commit to main"]
    commit --> start

加载中

• 笔记是简短的 markdown 文件，每条一个事实，采用 Claude Code 的记忆格式。
• 技能是如何再次完成一项工作，只有完成了该工作的运行才能写入一个。
• 学得的工作流在任何 harness 上作为一次工具调用运行，受该次运行自己的上限和工具权限约束。一旦学得的技能已服务 3 次运行，下一次运行就会被要求把该工作作为工作流草稿提出，草稿在保留前会先试运行：不询问模型，也不运行工具。

智能体的 Learning 标签页显示每条笔记、技能和工作流以及变更日志，每次运行会显示它被给予了哪些笔记、打开了哪些。在那里停用任何内容，或用 npx @parcha/agentrun learning retire 和笔记的 ETag 停用。Git 保留历史，因此停用的笔记可以恢复。

保留什么，丢弃什么

每个智能体都有一个学习文件夹：只有一个分支的普通 git，main。一次运行会在其指令中读取活动笔记的索引，并在自身技能旁获得学得的技能。代码会先检查每个提案。违反自身规则（大小或数量限制、名称、形状）的条目会被排除，其余继续。答案中任何位置的机密或隐藏字符、文件夹外的文件、删除或完整索引都会丢弃整个答案，因为其中任何条目都不可信。然后由一名评分者判断其内容，AgentRun 提交通过的内容。有风险的规则会等待你的确认。运行在页面或粘贴的电子邮件中发现的规则，或包含账号的笔记，会被丢弃。

一旦智能体的笔记超出学习预算，每次运行会完整获得与其第一条消息相关的笔记，其余每条获得一行。只运行了学得工作流的运行不会被询问要保留什么。

工作流

很多智能体不需要成为智能体。把可重复的工作写成类型化工作流：工具调用、模型步骤和快速的类型化决策（是或否、选一个、一个分数，每个都带置信度），并在案例不明确时有一个智能体作为后备。AgentRun 将其作为智能体的修订运行，受智能体的工具权限和像任何运行一样的上限约束，触发器可以启动一个。

_{examples/support-answer.mjs 中控制流的示意图，并非模型运行的录屏。}

逐节点查看任意工作流运行，暂停并恢复它，读取每个决策及其原因：

工作流长什么样

工作流是一份由带类型步骤组成的 JSON 文档：

{
  "v": 2, "name": "read-site",
  "schemas": {
    "In":   { "type": "object", "required": ["website"], "properties": { "website": { "type": "string" } } },
    "Page": { "type": "object", "required": ["ok"], "properties": { "ok": { "type": "boolean" } } }
  },
  "input":  { "schemaId": "In" },
  "output": { "schemaId": "Page", "path": "home" },
  "root": { "node": "chain", "steps": [
    { "node": "call", "label": "Read the home page", "via": "tool", "tool": "web_fetch",
      "args": { "url": "{website}" }, "out": "Page", "as": "home", "deadline_s": 60 }
  ] }
}

步骤可以调用工具、运行模型、提出一个快速的带类型问题、根据答案分支、并行映射列表、循环有界次数、调用其他工作流，或把棘手情况交给 agent。将其保存为 agent 的 workflow 字段；npx @parcha/agentrun workflows validate 会先检查它。工作流语言也能在你的应用内独立运行，并配有 TypeScript 构建器。

能挺过中断的运行

每个 agent、修订、运行和步骤都存放在同一个存储中。在运行中途停止服务器再重新启动，运行会继续。若有多个 runner，当某个 runner 的 30 秒租约到期后，另一个 runner 会接手它的运行。已完成的步骤绝不会再次运行；崩溃在调用中途截断的写入会被标记为已中断而非重试，以便你检查。

你始终掌控

• 审批。每个工具可设为允许、先询问你或拒绝。需要询问的调用会在运行页面上等待你的回答。“从不询问”让 agent 无人值守运行，而服务器上设置的拒绝仍然有效。
• 支出上限。为运行设置上限后，它会在此暂停而非失败，并告诉你继续所需的最低条件。AgentRun 无法定价的成本显示为“unknown”，绝不会是 $0。
• 提问。agent 可以停下来询问你，运行会等待你的回答。
• 一个控制台。每次运行都有实时时间线、其文件，若是浏览器还有可接管的屏幕。

模板

五个现成的 agent。在一个界面中应用一个，将其变为你的，并用它自己的评估用例来衡量。每个模板是一个文件夹：agent 的指令、技能、规则和评估用例。模板 → 应用在你亲自勾选每个 MCP 工具之前不会授予任何权限。

npx @parcha/agentrun template eval DIR 在一次性服务器上以真实运行执行模板的评估用例并评分。模板包说明了文件夹格式。

想让模板了解你的代码？在你自己的代码上调整模板 会带你走一遍我们在 code-review 上运行的循环。

触发器自行启动有上限的运行：计划、签名 webhook 和 GitHub 拉取请求事件。

Harness 与计算机

Harness。在 agent 定义中用 harness 指定一个。审批、上限、计算机、触发器和学习在每个 harness 上工作方式相同。npx @parcha/agentrun server capabilities 说明你的服务器运行哪些 harness。

计算机。智能体获得一台只有一种设置的计算机。它只获得该类计算机对应的工具，别无其他；更换计算机不会改变智能体的其他任何方面。

computer:
  kind: sandbox        # none, sandbox, desktop, phone or browser
  provider: daytona    # one you connected in Settings → Computers (none takes no provider)

除 none 外，每种类型都会指明其提供商。未设置计算机的智能体会获得 Docker 沙箱（前提是服务器上有 Docker），否则就没有计算机。远程计算机通过你与供应商自己的账户计费。

密钥、运行文件、接管与一致性

• 密钥。在 Settings → Computers 中一次性添加供应商的密钥。你的服务器会将其密封保存，仅显示为已设置或缺失；它绝不会进入智能体的计算机。Test connection 只会在供应商处执行一次读取，不会启动任何东西。
• 运行的文件。默认情况下，运行的文件夹位于你的服务器上，Docker 沙箱会挂载它。在设置中开启 Archil 磁盘后，文件夹会改为存放在那里，因此 Daytona、Modal 或 E2B 沙箱会挂载同一个文件夹。这三种沙箱只能配合 Archil 磁盘运行，而开启 Archil 后 Docker 沙箱会被拒绝。
• 观看与接管。浏览器运行会通过你自己的服务器流式传输到运行的 Screen 标签页，绝不经过供应商链接。你可以接管控制权，然后再交还。智能体也可以暂停并请求你接管，以处理登录或验证码。
• 证明。每个提供商都有针对其类型的一致性测试套件。在 npm ci && npm run build 之后，从检出目录自行对供应商运行它： npm run conformance -w @parcha/agentrun-computer -- --provider docker --kind sandbox。

@parcha/agentrun-computer 是底层协议：每台计算机中有一个小型守护进程，每个供应商对应一个提供商。

各部分如何组合

flowchart LR
    you["Console · CLI · API"] --> server["Server"]
    server --> store["One store<br/>SQLite or Postgres"]
    runner["Runners"] -->|claim runs| store
    runner --> hands["Hands<br/>run folder + computer"]

加载中

• 服务器。在 /v2 提供 API 和控制台。它将运行和命令写入存储，并为你读回。当你用 --no-runner 启动它时，它本身不运行智能体循环。
• 存储。智能体、修订、运行以及每次运行的日志，都集中在一处。默认使用数据文件夹中的 SQLite，或使用 Postgres 配合 AGENTRUN_STORE_URL。
• 运行器。每个运行器从存储中认领运行，并可同时运行多个。每次审批检查、上限和模型调用都在这里发生。添加运行器以横向扩展。
• 执行端。智能体工具实际作用的地方。每次运行都有一个用于存放其文件的运行文件夹。沙箱将该文件夹挂载到 /workspace，工具在其中运行；桌面、手机或浏览器则将该文件夹留在运行器上。

从终端和从代码

npx @parcha/agentrun 也是服务器的 CLI。在服务器运行时，在第二个终端中运行这些命令；CLI 会自行找到服务器及其令牌。该脚本会创建一个智能体，启动一次上限为 $1 的运行，让智能体向你提问，回答该问题，并读取智能体写入的文件。开启 Docker 后，首次运行会等待沙箱镜像。

# 1. Make an agent that can write files and ask you things.
cat > agent.json <<'EOF'
{"definition": {"id": "notes", "version": 1, "name": "Notes",
  "instructions": "Do what you are asked, and write what you make to a file.",
  "skills": [], "tools": ["write", "ask_person"]}}
EOF
npx @parcha/agentrun agents create --body @agent.json

# 2. Start a capped run and wait. It stops to ask you which region (exit code 8: it waits on you).
npx @parcha/agentrun runs start notes --max-cost-usd 1 --wait \
  --body '{"input": {"content": "Ask me which region to cover, then write region.md about it."}}' > out.json

# 3. Answer, wait for it to finish, and read what it wrote.
run=$(node -p 'require("./out.json").run_id')
npx @parcha/agentrun runs message "$run" --content "Europe"
npx @parcha/agentrun runs wait "$run" > out.json
npx @parcha/agentrun runs read-file "$run" region.md

当运行完成时，runs wait 退出码为 0；失败时为 1；当它等待你时（一个问题、其上限或一次审批）为 8。runs timeline RUN_ID --follow 会实时流式输出每一步，每次运行都会在其页面上带有一个 console_url。npx @parcha/agentrun help 列出所有命令；npx @parcha/agentrun skill install --claude（或 --codex）会向你的编码代理教授该 CLI。

从 TypeScript 或 Python 发起同样的运行

使用 TypeScript 客户端（npm install @parcha/agentrun-client，无依赖）。客户端从环境变量读取其服务器和令牌；服务器启动时会打印两者（使用 npx @parcha/agentrun 时，令牌位于 ~/.agentrun/.token 中，地址通常为 http://127.0.0.1:7340）：

export AGENTRUN_BASE_URL=http://127.0.0.1:7340/v2
export AGENTRUN_API_KEY=$(cat ~/.agentrun/.token)

import { AgentRun } from "@parcha/agentrun-client";

const client = new AgentRun(); // AGENTRUN_BASE_URL and AGENTRUN_API_KEY
const started = await client.runs.start("notes", { input: { content: "Ask me which region to cover, then write region.md about it." }, max_cost_usd: 1 });
let run = await client.runs.wait(started.run_id);
if (run.pending?.kind === "question") await client.runs.message(run.run_id, { content: "Europe" });
run = await client.runs.wait(run.run_id);
console.log(run.status, run.cost.usd);

Python 客户端是 pip install parcha-agentrun，具有相同的方法（TypeScript 客户端、Python 客户端）。

部署它

Render，一键部署。

该按钮会部署 render.yaml：一个 1 CPU / 2 GB 实例，配有 10 GB 磁盘，使用已发布的镜像（无需构建），并为你生成令牌和密封密钥。它需要你的 Render 工作区绑定一张卡：按本文撰写时 Render 的价格，实例约每月 $25，磁盘 $2.50。在 Render 的表单中，粘贴 OPENROUTER_API_KEY。我们建议使用带有美元上限和到期日期的 OpenRouter 密钥。不要与任何人分享此密钥。上线后，打开其 URL，并从服务的 Environment 标签页粘贴 AGENTRUN_TOKEN 来设置你的密码。

Docker Compose：一个服务器和两个运行器

在装有 Docker 的 Linux 机器上：

git clone https://github.com/Parcha-ai/agentrun && cd agentrun/deploy
printf 'AGENTRUN_SEAL_KEY=%s\n' "$(openssl rand -base64 32)" > .env && chmod 600 .env
echo 'OPENROUTER_API_KEY=...' >> .env
docker compose up -d --build
docker compose logs server     # the console's link, the first visit's setup code and, the first time, the token

该端口仅发布在此机器的回环地址上；在向其他人开放之前，请在前面放置一个 TLS 代理。此 compose 文件没有 Docker socket，因此其代理获得文件工具和 web_fetch，但没有 shell。如需 Docker 沙箱，请使用仓库根目录下的单服务器 compose.yaml（Docker Engine 26 或更高版本），在主机上运行服务器，或使用带有 Archil 磁盘的 Daytona 或 E2B 计算机。

Postgres 上的运行器

在服务器和每个运行器上将 AGENTRUN_STORE_URL 设置为 postgres:// URL（compose 文件的 pg 配置文件会运行一个），使用 --no-runner 启动服务器，并使用 runner --data /data --name <name> 从同一镜像启动每个运行器。为每个进程提供相同的 AGENTRUN_SEAL_KEY。在此版本中，运行器仍共享 /data 卷。

部署 AgentRun 涵盖运行器、健康检查和升级。

安全

每个保存的机密（模型和工具密钥、MCP 凭据、登录信息、webhook 签名机密）都在一个密钥下密封，AGENTRUN_SEAL_KEY；请保留它，因为丢失它就会丢失它所密封的内容。机密是只写的：控制台将每个机密显示为已设置或缺失，并且只有控制台可以粘贴、替换或移除机密（你已登录的会话，或当账户关闭时回环地址上的启动器控制台）。在服务器启动处设置的密钥优先于粘贴的密钥。API 令牌不能写入机密或批准工具调用。一次运行只获得其自身模型和工具所需的密钥，并且运行所学到的任何内容都无法保留交给它的机密。SECURITY.md 说明了如何报告漏洞。

文档

• AgentRun Server：API、模型、工具、MCP 服务器、触发器、支出上限、学习和安全，完整说明
• agentrun.ai 上的快速入门和文档
• CLI 的技能和每个命令
• 部署、计算机、模板
• 工作流语言、编写、指南
• 变更日志和贡献

接下来

• 按调用选择计算机，而不仅按代理选择
• 第一方计算机
• iPhone、macOS 和 Windows 计算机
• 像今天的浏览器运行一样，观看并接管桌面或手机运行
• 将 Composio 作为工具目录
• 基于 Agent Client Protocol 的 Harness
• Slack 触发器和 Parallel 监控触发器

许可证与致谢

Apache-2.0。Copyright 2026 Parcha Labs, Inc. 由 Grep.ai 构建。

AgentRun 基于 Earendil Works 的 pi（MIT），即其下的 agent 循环与持久化运行时；Stagehand 与 Browserbase Node SDK；TypeSafe JavaScript SDK；Archil 的 disk SDK；以及 vercel-labs/durable-harness（Apache-2.0），持久化 harness 构建于其理念与代码之上。各自保留其自身许可证；每个包的 NOTICE 列出了其所包含的内容。