AgentRun：开源自改进Agent平台，降低token成本

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

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

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

AgentRun 是一个开源平台，能为你的智能体提供强大支持。它在您最喜欢的智能体运行框架之上添加了自我改进、持久执行和控制平面。您的智能体变得更加智能、更具容错能力，并且每次运行使用的 token 更少。

某个智能体的 Learning 标签页：它保留了哪些内容，以及此后发生了哪些变化。演示数据来自控制台的录制固件。

案例研究

代码审查。 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。

npx @parcha/agentrun

1. 启动它。 它在端口 7340（或下一个空闲端口）上启动服务器和一个运行器，将所有内容保存在 ~/.agentrun 中，并在浏览器中打开控制台。
2. 添加一个模型密钥。 在控制台中设置密码，然后在 Settings → Model keys 下添加一个密钥。一个 OPENROUTER_API_KEY 就能为每个框架提供一个模型。Anthropic 密钥可运行 pi 和 Claude Code；OpenAI 密钥可运行 pi、Codex 和 OpenCode。
3. 运行你的第一个智能体。 打开 Templates，应用 KYB 尽职调查，然后用一家公司的名称和网站启动一次运行。它只需要你的模型密钥。完成后，运行的 Report 标签页中会有一份尽职调查报告，包含结论和每一条被引用的说法。然后打开该智能体的 Learning 标签页，看看它为下次保留了哪些内容。

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

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

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

开始导览

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

每个智能体都在一处。 任务控制中心首先打开：哪些需要你、哪些失败了、哪些正在运行以及花费多少，按天、按框架和按工具。

每个智能体都是一个 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 的记忆格式。
• 技能 是如何再次完成一项工作，只有完成了该工作的运行才能写入一个技能。
• 已学习的工作流 在任何框架上都作为一次工具调用运行，受该运行自身的上限和工具权限约束。一旦学到的技能已服务 3 次运行，下一次运行就会被要求为那项工作提供一个工作流草稿，草稿在保留前会进行试运行：不询问模型，也不运行工具。

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

哪些内容会被保留，哪些会被丢弃 每个 Agent 都有一个学习文件夹：纯 git，只有一个分支，main。一次运行会从它的指令中读取活动笔记的索引，并在自身笔记旁获取已学到的技能。代码会先检查每一个提案。违反自身规则（大小或数量限制、名称、形状）的条目会被剔除，其余条目继续处理。答案中任何位置的机密或隐藏字符、文件夹之外的文件、删除操作或完整索引都会使整个答案被丢弃，因为其中的任何条目都无法被信任。然后由一个评分器评判它所说的内容，AgentRun 提交通过的部分。有风险的规则会等待你的确认。运行从页面或粘贴的电子邮件中发现的规则，或持有账号的笔记，都会被丢弃。

一旦某个 Agent 的笔记超出了学习预算，每次运行都会完整获得与其第一条消息相关的笔记，以及其余每条笔记的一行摘要。仅运行了已学习工作流的运行不会被询问要保留什么。

工作流

很多 Agent 并不需要成为 Agent。把可重复的工作写成一个有类型的工作流：工具调用、模型步骤和快速的类型化决策（是或否、选择一个、一个分数，每项都带有其置信度），并在情况不明确时回退到 Agent。AgentRun 将其作为 Agent 的一个修订版运行，在 Agent 的工具权限和类似任何运行的额度上限下运行，触发器可以启动它。

控制流示意图，位于 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、修订版、运行和步骤都存放在同一个存储中。在运行中途停止服务器并重新启动，运行会继续。有多个运行器时，另一个运行器会在某个已死运行器的 30 秒租约到期后接管其运行。已完成的步骤永远不会再次运行；崩溃时在调用中途被切断的写入会被标记为已中断，而不是重试，因此你可以检查它。

你始终掌握控制权

• 审批。 每个工具要么被允许，要么先询问你，要么被拒绝。会询问的调用会在运行页面上等待你的回答。“从不询问”让 Agent 无人值守运行，而服务器上设置的拒绝仍然对其有效。
• 支出上限。 给一个运行设置上限，它就会在那里暂停而不是失败，并告诉你继续所需的最少内容。AgentRun 无法定价的成本显示为“未知”，绝不是 $0。
• 问题。 Agent 可以停下来问你，运行会一直等到你回答。
• 一个控制台。 每次运行都有一个实时时间线、它的文件，对于浏览器，还有一个你可以接管的屏幕。

模板

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

npx @parcha/agentrun template eval DIR 在一个一次性服务器上以真实运行的方式运行模板的评估用例，并对它们评分。 模板包 有文件夹格式。

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

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

连接你的工具

在 设置 → MCP 服务器 中，将任何远程 MCP 服务器的工具提供给 Agent。使用 Composio 密钥，五步即可从一个工具包走到由 Composio 事件启动的运行：

1. 在 设置 → MCP 服务器 → 从 Composio 添加 中，粘贴你的 Composio API 密钥，输入一个工具包（hackernews）并按 加载动作。
2. 保存一个以你的身份行事的工具包，例如 github，并打开其链接在 Composio 上连接你的账号。
3. 勾选 Agent 可以使用的动作并保存服务器，然后在 Agent 的 工具与技能 步骤中勾选它的工具。
4. 在 触发器 → 新建 webhook 中，选择 Composio 的签名和 Agent，在 Composio 上订阅其 URL，然后用 设置密钥 粘贴 Composio 的密钥。
5. 在你的仓库中打开一个 issue，并在 时间线 上观看它启动的运行。

连接 Composio 工具与触发器 有每个步骤的 API 调用以及触发器在 Composio 一侧的设置。

测试框架与计算机

测试框架。 在 agent 的定义里指定一个，使用 harness。审批、额度上限、计算机、触发器和学习在每一个上都以相同方式工作。 npx @parcha/agentrun server capabilities 会说明你的服务器运行哪些 harness。

计算机。 一个 agent 通过一项设置获得一台计算机。它只获得该类型的工具，别的什么都没有，而且更改计算机会改变该 agent 的其他任何东西。

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

除 none 以外的每一种类型都会指明其提供方。没有设置 computer 的 agent 在服务器有 Docker 时会获得 Docker sandbox，否则没有计算机。远程计算机通过你自己在供应商处的账户计费。

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

• 密钥。 在 设置 → 计算机 中一次性添加供应商的密钥。你的服务器会将其密封，并且只显示为已设置或缺失；它绝不会进入 agent 的计算机。 测试连接 会在供应商处执行一次读取，不会启动任何东西。
• 运行的文件夹。 默认情况下，一次运行的文件夹位于你的服务器上，Docker sandbox 会挂载它。在设置中开启 Archil 磁盘后，该文件夹就改为存放在那里，并且 Docker sandbox 会被拒绝。Modal、E2B 或 Agent37 sandbox 需要在你自己的供应商账户中拥有 Archil 的镜像，而你的服务器目前还无法把该镜像放到那里：设置会显示它们未就绪，因此开启 Archil 时，目前不会运行任何 sandbox。
• 观看和接管。 浏览器运行会通过你自己的服务器、而不是供应商链接，流式传输到该运行的 屏幕 标签页。接管控制权，然后再交还。该 agent 也可以停下来请你接管，以处理登录或验证码。
• 验证。 每个提供方都有一套针对其类型的一致性测试套件。请你自己针对供应商运行它，在 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 启动它时，它自身不运行任何 agent 循环。
• 存储。 Agent、修订版本、运行以及每次运行的日志，都在同一个地方。默认是数据文件夹中的 SQLite，或通过 AGENTRUN_STORE_URL 使用 Postgres。
• 运行器。 每个运行器从存储中认领运行，并同时运行多个。每次审批检查、额度上限和模型调用都在这里发生。添加运行器以横向扩展。
• Hands。 agent 的工具执行之处。每次运行都有一个用于其文件的运行文件夹。sandbox 会把该文件夹挂载到 /workspace，工具在其中运行；desktop、phone 或 browser 则把文件夹留在运行器上。

从终端和从代码

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

# 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

运行等待 在运行完成时退出码为 0，失败时为 1，在等待你时退出码为 8：一个问题、它的额度上限或一次审批。 runs timeline RUN_ID --follow 会在每一步发生时流式输出它，而且每次运行都带有一个 console_url 指向它的页面。 npx @parcha/agentrun help 会列出所有命令；npx @parcha/agentrun skill install --claude（或 --codex）会让你的编码 agent 学会该 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";constclient=newAgentRun();// AGENTRUN_BASE_URL and AGENTRUN_API_KEYconststarted=awaitclient.runs.start("notes",{input: {content: "Ask me which region to cover, then write region.md about it."},max_cost_usd: 1});letrun=awaitclient.runs.wait(started.run_id);if(run.pending?.kind==="question")awaitclient.runs.message(run.run_id,{content: "Europe"});run=awaitclient.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，因此其 agent 获得文件工具和 web_fetch，但没有 shell。要使用 Docker sandbox，请使用仓库根目录下的单服务器 compose.yaml（Docker Engine 26 或更高版本），在主机上运行服务器。

Postgres 上的运行器 将 AGENTRUN_STORE_URL 设置为服务器和每个运行器上的 postgres:// URL（compose 文件的 pg profile 会运行一个），用 --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 的技能和每条命令
• 部署、计算机、模板
• 连接 Composio 工具和触发器
• 工作流语言、编写、指南
• 变更日志和贡献

接下来

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

许可证与致谢

Apache-2.0。版权所有 2026 Parcha Labs, Inc. 由Grep.ai构建。

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