Ship quickly. Prove value. Scale with control.

快速接入，验证价值，再稳步扩展。

Build enterprise-grade multi-agent runtimes that are ready to launch and ready to operate. 快速搭建可上线、可运维的企业级多智能体运行时。

agent-harness is the workspace-shaped runtime for multi-agent products. It adds approvals, recovery, inspection, operator controls, and protocol-ready surfaces on top of your agents—so you ship operable software, not only prompts. The harness owns the product runtime layer around your existing execution stack.

agent-harness 是以工作区为单位的多智能体产品运行时：在智能体之上提供审批、恢复、运行检查、运维管控与协议接入，帮你交付能长期运维的系统，而不止于调模型。harness 负责现有执行栈之外的运行时层。

Recommended method: one sentence to let your coding agent build a complex runtime application推荐方式：一句话让 coding agent 构建复杂运行时应用

Follow https://botbotgo.github.io/agent-harness/SKILL.md to build a stock deep research runtime application.

Alternative method: start one runtime in a few lines另一种方式：几行代码即可启动运行时

import { createAgentHarness, request, stop } from "@botbotgo/agent-harness";

const runtime = await createAgentHarness("/absolute/path/to/workspace");
const result = await request(runtime, {
  agentId: "auto",
  input: "Explain what this workspace is for.",
});
console.log(result.output);
await stop(runtime);

What to align on before you scale

上线前值得对齐的三点

Is it enterprise-grade and operable? 是否企业级、可运维？
Yes—persisted requests, approvals, recovery, audit-friendly records, and operator tooling are first-class, not bolted on after the demo.

是。持久化运行记录、审批、恢复、审计与运维能力均为内置能力，而不是演示后再打补丁。
How fast can we ship a runtime? 多快能搭好一套运行时？
Point at a workspace, wire YAML, connect tools and MCP, and stand up approvals, recovery, and inspection behind a small API—without building bespoke runtime plumbing.

指定工作区目录，写好 YAML，接入工具与 MCP，通过精简的 API 即可获得审批、恢复与可观测能力，无需从零搭建运行时底座。
What do we get on day one? 第一天能拿到什么？
Persisted requests and sessions, human approvals, restart-safe recovery, protocol surfaces, and operator-facing records you can inspect right away.

持久化的请求与会话、人工审批、进程重启后仍能恢复运行、协议侧接入能力，以及可查可管的运维台账。

In practice: one small API plus YAML assembly; execution stays upstream while persistence, approvals, and recovery stay runtime-owned.

落地方式：精简 API + YAML 装配；执行语义留在上游，持久化、审批与恢复由运行时统一托管。

npm install @botbotgo/agent-harness More detail in the developer docs below. 更多说明见下文开发文档。

See quick integration path 查看快速接入 Why it fits cleanly 为何易于集成 See product scope查看产品模块 Technical docs 技术文档 See commercial support查看商业支持

At a glance: you ship a stable runtime contract quickly, with operating controls built in from day one—not a framework science project.

快速了解：能尽快交付稳定的运行时契约，运维能力从第一天就内置——而不是长期堆原型、拼框架。

Commercial support: optional help with deployment, launch, and operator handoff after you decide the runtime fits.

商业支持：方案合适后，可按需选购部署指导、上线协助与运维交接等服务。

Technology 技术模块

Lead with the practical: how the runtime turns a workspace into an operable product layer—then approvals, recovery, protocol bridges, and operator control.

从「工作区如何变成可运维的产品层」讲起，覆盖审批、恢复、协议桥接与运维控制，用可落地的机制代替抽象定义。

Boundary边界

Where agent-harness fits定位与对比

Comparison docs show how agent-harness relates to people-facing agent products, execution frameworks, and workflow automation tools.

对比文档说明 agent-harness 与面向人的智能体产品、执行框架和工作流自动化工具各自的定位与关系。

Persistence持久化

Persisted runtime records持久化运行时记录

Requests, sessions, approvals, events, and artifacts are treated as stable runtime records rather than incidental backend output.

将 requests、sessions、approvals、events、artifacts 视为稳定的运行时数据，而不是执行引擎旁路的临时输出。

Recovery恢复

Recovery and operator control恢复与运维控制

The runtime owns interruption handling, restart recovery, approval continuation, and operator-facing inspection.

由运行时处理中断、重启恢复、审批续跑与面向运维的可观测能力。

Protocols协议

Protocol-ready surfaces协议接入

ACP, A2A, AG-UI, and runtime MCP are exposed as stable transport surfaces instead of one-off integration demos. MCP stays the resource/tool plane, A2A stays the agent-to-agent task bridge, ACP is the primary editor-or-client boundary, and runtime MCP exposes the operator control plane outward.

将 ACP、A2A、AG-UI 与 runtime MCP 作为稳定的对外接入面，而不是零散的集成示例。MCP 负责连接资源与工具，A2A 负责智能体平台之间的任务协作，ACP 是编辑器或客户端接入运行时的主边界；runtime MCP 则把运维控制能力以统一接口对外暴露。

YAMLYAML

Workspace assembly in YAML用 YAML 装配工作区

Routing, models, tools, MCP, maintenance, and policy live in YAML so complex runtime assembly stays explicit and reviewable.

路由、模型、工具、MCP、维护与策略写在 YAML 里，复杂装配一目了然，便于评审。

Adapters适配器

Upstream-aligned adapters与上游对齐的适配器

Execution frameworks stay upstream-owned; adapters use them deeply without redefining a second agent framework.

执行框架仍由上游定义；适配器深度复用其能力，不再自造一套智能体框架。

Compare when you need to choose需要选型时再看对比

Legend: ✅ (default) · ⚪ (opt-in / middleware-backed) · ❌ (not in public runtime contract).

图例：✅（默认） · ⚪（可选/依赖中间件） · ❌（不在公开契约中）。

Execution frameworks own agent execution. n8n owns workflow automation. agent-harness operates the application runtime layer for multi-agent products.

执行框架负责智能体执行语义；n8n 侧重工作流自动化；agent-harness 提供多智能体产品所需的运行时层。

Use this matrix after you have a rough picture of agent-harness—it helps you validate fit, not replace the intro.

对 agent-harness 有大致了解后再用本表做选型对照；它不能替代入门阅读时的概念说明。

Capability能力 General-purpose execution frameworks通用执行框架 Planner-first execution runtimes规划优先执行运行时 n8nn8n agent-harnessagent-harness

Execution model执行模型

Agent execution semantics执行语义 ✅ `createAgent` runtime + middleware✅ `createAgent` 运行时 + 中间件 ✅ `createDeepAgent` runtime✅ `createDeepAgent` 运行时 ⚪ Workflow nodes and triggers, not agent-runtime execution semantics⚪ 以节点与触发器为主，不是面向智能体的运行时执行语义 ✅ Preserves upstream runtime, declares policy in YAML✅ 基于上游执行语义，使用 YAML 统一装配

Model + tool orchestration模型与工具编排 ✅ Native graph + tool-calling execution path✅ 原生图执行 + 工具调用体系 ✅ Planner-guided multi-action execution✅ 规划驱动的多步执行链 ⚪ Strong workflow automation, limited agent-native orchestration semantics⚪ 擅长工作流自动化，面向智能体的编排能力有限 ✅ Via upstream runtimes, normalized through YAML workflow✅ 基于上游运行时，使用 YAML 统一装配

Tools, skills, and resource catalogs工具、技能与资源目录 ✅ Native tools + middleware-compiled skill and sub-agent wiring✅ 原生工具链 + 中间件编译的技能/子代理装配 ✅ Native tools, skills, and backend-mounted execution inputs✅ 原生工具、技能与后端挂载执行输入 ⚪ Large integration catalog, but not a reusable agent workspace contract⚪ 集成目录丰富，但缺少可复用的智能体工作区契约 ✅ Workspace compiler + cataloged objects/resources and reusable mounts✅ 工作区编译器、目录化对象/资源与可复用挂载

Runtime control and operator surface运行时控制与操作面

Human-in-the-loop人工干预（HITL） ✅ HITL middleware support✅ 中间件层支持 HITL ✅ interruptOn and approval hooks✅ interruptOn / 审批钩子 ⚪ Workflow approvals exist, but not shared persisted approval records⚪ 有流程审批，但无统一的智能体审批记录模型 ✅ Shared persisted approval records, inspectable + resolvable✅ 统一审批记录、查询与流转

Operator approval inbox运维审批收件箱 ❌ Middleware hooks exist, but no shared operator inbox product surface❌ 有中间件钩子，但无统一的运维审批收件箱 ⚪ Approval stops exist in execution, not a runtime-owned inbox and queue⚪ 执行中会暂停待审批，但无运行时托管的审批收件箱与队列 ✅ Native manual steps and operator review flows✅ 原生支持人工环节与操作员审核流 ✅ Shared approvals API, inspectable queue, and resumable decisions✅ 统一的 approvals API、可查队列、可续跑的审批决策

Structured output / response constraints结构化输出 ✅ Native response format and schema support✅ 原生 response format 与 schema 能力 ✅ ResponseFormat and context schema✅ responseFormat 与 context schema 支持 ⚪ Node-by-node shaping, not agent-model-native response contracts⚪ 偏节点级数据整形，非模型侧原生输出契约 ✅ Preserved from upstream and exposed via run outputs✅ 上游透传并在运行记录中保留

State, persistence, and audit状态、持久化与审计 ⚪ Checkpoint-native state, not persisted runtime request/session/approval records⚪ checkpoint 为主导，非产品级运行记录 ⚪ Checkpoint-native state, not persisted runtime request/session/approval records⚪ checkpoint 为主导，非产品级运行记录 ⚪ Workflow history exists, not a unified multi-agent runtime record model⚪ 有流程历史，但无统一的多智能体运行记录模型 ✅ Harness-owned request/session/approval/event records✅ 持久化 `requests/sessions/approvals/events/artifacts`

Tool-call recovery (patch tool calls)工具调用恢复（补丁重放） ✅ Enabled by default via adapter-level automatic middleware✅ 默认由适配器级自动中间件开启 ✅ Native patch-tool-call recovery path✅ 内置补丁恢复路径 ❌ Retry/restart workflow steps, not model tool-call patch recovery❌ 可重试流程步骤，但不提供模型工具调用补丁恢复 ✅ Enabled for both backends by default✅ 两端默认开启，统一由运行时承载

Planning and to-do behavior规划与任务清单行为 ⚪ Upstream model does not enforce planning-first workflow⚪ v1 侧无内置「先规划再执行」的默认流程 ✅ Native planning/to-do execution behavior✅ 内置规划与 to-do 机制 ❌ Flow logic and branching, not agent planning/to-do semantics❌ 有流程分支，但不具备智能体规划与待办语义 ✅ Preserved when the chosen execution backend exposes planning-first behavior✅ 当所选执行后端具备规划优先行为时可直接保留

Operations, recovery, and production delivery运维、恢复与生产交付

Backend presets and reusable catalogs后端预设与复用目录 ❌ Runtime composition via framework-specific bootstrap❌ 通过框架自有启动方式组装 ✅ Backend preset and catalog workflow✅ 后端 preset 与目录化加载 ❌ Workflow templates, not backend/runtime preset catalogs for agent apps❌ 有流程模板，但非面向智能体应用的后端/运行时预设目录 ✅ Shared workspace-first catalog and mount model✅ 统一工作区层支持复用和版本管理

Runtime triggers and entrypoints运行时触发器与入口 ❌ Agent invocation exists, but not a product runtime ingress contract❌ 可调用智能体，但无产品级运行时入口契约 ⚪ Execution start points exist, but not a stable host/runtime ingress surface⚪ 有执行入口，但无稳定的主机/运行时接入层 ✅ Webhooks, schedules, and manual triggers for operator-facing workflows✅ 面向操作员工作流的 webhook、定时与手动触发 ✅ Stable runtime start/request surface that host apps can expose behind their own ingress✅ 提供稳定的 `start`/`request` 接口，宿主应用可挂到自己的入口层之后

Production operations生产运维 ⚪ Basic lifecycle hooks only⚪ 仅有基础生命周期钩子，运维需应用侧补齐 ⚪ Execution-level lifecycle only⚪ 侧重执行层生命周期，运维能力需自行扩展 ⚪ Operational workflow automation, not agent runtime recovery and isolation⚪ 擅长运维自动化，但不覆盖智能体运行时的恢复与隔离 ✅ Queueing, concurrency, approvals, recovery, maintenance✅ 队列并发、审批流、恢复、checkpoint 维护、运行生命周期

Failure handling and resume policy失败处理与恢复策略 ⚪ Framework recovery primitives exist, but app-level retry and resume policy is left to the host⚪ 有框架恢复原语，但应用级重试与恢复策略需宿主自行实现 ⚪ Checkpoint resume exists, not a product-owned recovery policy layer⚪ 有 checkpoint 恢复，但不是产品自带的恢复策略层 ✅ Retries, error branches, and manual reruns at the workflow layer✅ 工作流层支持重试、错误分支与人工重跑 ✅ Runtime-managed recovery, approval continuation, and checkpoint maintenance policy✅ 运行时托管恢复、审批续跑与 checkpoint 维护策略

Request queue and concurrency policy请求队列与并发策略 ❌ No product-facing request queue contract❌ 没有产品级请求队列契约 ⚪ Execution concurrency exists, not a host-level request queue and policy surface⚪ 有执行并发，但无宿主级请求队列与策略接口 ✅ Queue mode and workflow concurrency controls✅ 队列模式与工作流并发控制 ✅ Host-level request queue, priorities, leaseing, and max-concurrency policy✅ 宿主级请求队列、优先级、租约与最大并发策略

How to use in production生产接入方式 ⚪ Build app-specific orchestration and lifecycle wrappers⚪ 应用需自行补齐运维与编排 ⚪ Focused on execution path, not full product lifecycle⚪ 偏向执行层能力封装 ⚪ Great for app and ops automation; limited product runtime surface for multi-agent apps⚪ 适合应用与运维自动化，但多智能体产品运行时能力较弱 ✅ Small API: createAgentHarness/request/subscribe/resolveApproval/stop/getHealth; inspect requests/sessions/approvals✅ 小而稳的运行时 API：createAgentHarness/request/subscribe/resolveApproval/stop/getHealth，查询 requests/sessions/approvals/health

Workspace + YAML platform工作区 / YAML 平台化 ⚪ Framework-level composition, limited workspace-level declarative control⚪ 框架主导组装，声明式控制有限 ⚪ Runtime-first with backend-driven config, limited cross-project catalogs⚪ 运行时为主，workspace 平台化层有限 ❌ Workflow builder, not workspace-shaped YAML assembly for agent products❌ 流程搭建器，不是面向 agent 产品的 workspace YAML 装配 ✅ Workspace compiler + declarative catalogs✅ 支持工作区编译器、对象目录、声明式配置

Sessions, requests, and events会话、请求与事件 ⚪ Framework tracing primitives without unified runtime record schema⚪ 框架追踪原语，无统一运行记录结构 ⚪ Native eventing in execution scope⚪ 执行级事件能力，非统一产品运行图 ⚪ Run history and logs per workflow, not unified runtime records across agents⚪ 有流程运行历史与日志，但无跨智能体的统一运行记录 ✅ Unified `requests`/`sessions`/`events` and approval streams✅ 统一 `requests` / `sessions` / `events` 与审批流

Operator control plane运维控制台能力 ❌ Framework primitives, but no app-runtime control plane for requests and approvals❌ 有框架原语，但没有面向应用运行时的 requests / approvals 控制台能力 ⚪ Execution-native visibility, not a stable product control plane contract⚪ 有执行侧可见性，但无稳定的产品控制台契约 ✅ Workflow run history, retry controls, and operator-facing execution UI✅ 工作流运行历史、重试控制与面向操作员的执行界面 ✅ Requests, sessions, approvals, health, and event streams through one stable runtime API✅ 通过统一运行时 API 暴露 requests、sessions、approvals、health 与事件流

The difference is not replacing execution engines. It is the operating layer that makes those engines production-ready.

重点不是替换执行引擎，而是让现有执行引擎具备可上线、可运维、可恢复的应用运行时能力。

Product产品模块

Beyond mechanics, the product question is what you and your operators can count on every day.

除了机制本身，更要看清你和运维团队每天都能依赖哪些能力。

1. Runtime API1. Runtime API

A deliberately small API around `createAgentHarness`, `request`, approvals, inspection helpers, memory, artifacts, and stop.

围绕 `createAgentHarness`、`request`、审批、查询辅助接口、记忆能力、产物读取与 `stop` 组织成的一套精简 API。

2. Runtime operations2. 运行时运维

Approval queues, recovery, queueing, runtime health, event inspection, and operator overview belong to the product runtime.

审批队列、恢复、排队、运行时健康、事件排查与运维总览均由产品运行时负责。

3. Workspace model3. 工作区模型

Agents, catalogs, tools, skills, MCP, and policy are assembled through a workspace-shaped configuration model.

以工作区形态的配置模型装配 agents、catalogs、tools、skills、MCP 与策略。

4. Protocol adapters4. 协议适配器

External clients can integrate through ACP, A2A, AG-UI, and runtime MCP without redefining the product runtime surface. The thinnest local starter is ACP over stdio for IDE or CLI sidecars.

外部系统可通过 ACP、A2A、AG-UI 与 runtime MCP 接入，无需再造一套产品运行时模型。若想从最轻量的本地接入方式开始，优先使用面向 IDE 或 CLI 侧车进程的 ACP stdio。

5. Common deployment patterns5. 常见部署形态

Enterprise internal agent runtime, coding-flow runtime, protocol bridge runtime, and governed multi-agent applications.

企业内智能体运行时、编码类长流程运行时、协议桥接运行时，以及受治理的多智能体应用。

Commercial商业支持

Commercial support covers deployment guidance, production hardening, and team handoff when you want help beyond the open-source runtime—see default scope and exclusions below.

需要部署协助、生产加固或团队交接时，可选择商业服务；下方说明默认包含的范围与需单独约定的部分。

Default commercial scope默认商业范围

Deployment and integration guidance部署与接入指导
Initial launch assistance and hardening初期上线协助与加固
Protocol, tool, and connector adaptation help协议、工具和连接器适配支持
Runbooks, handoff, and limited advisory support操作手册、交接和有限顾问支持

Not included by default默认不包含

Managed production operations代为托管的生产运维
On-call coverage and long-term run-the-system work长期值班与代运营
Open-ended transformation consulting before scope is defined范围未定时的大而泛的转型咨询
Ongoing responsibility outside the runtime boundary without a written scope未书面约定却超出运行时边界的长期责任

Rollout practices that work可借鉴的稳妥上线做法

Treat the runtime as product infrastructure: start with one measurable workflow, keep humans in the loop where the business needs them, plug into tools teams already use, and ship observability alongside the workflow.

把运行时当作产品基础设施：从一条可度量的流程做起，在业务需要处保留人工环节，接入团队已在用的系统，并与流程同步交付可观测性。

Start with one workflow you can measure从一条可度量的流程开始

Pick one team and one repeated task to improve before broad “transformation” scope creep sets in.先明确「哪个团队、哪条重复任务要改善」，再扩展范围，避免空泛的转型清单。

Keep human review where the business needs it在业务需要处保留人工复核

Build approvals, escalations, and manual takeover into the first version so pilots can touch real risk boundaries safely.第一版就纳入审批、升级与人工接管，试点才能覆盖真实风险边界。

Meet people in the tools they already use接入团队已在使用的系统

Surface answers, summaries, tickets, and approvals in email, docs, chat, or ticketing—where work already happens.把回复、摘要、工单与审批放在邮件、文档、聊天或工单等现有工作界面里，降低切换成本。

Ship logs and visibility with the workflow与流程同步交付日志与可见性

Make it possible to inspect what happened and intervene when something goes wrong—before you scale usage.在扩大使用面之前，先能看清发生了什么并在异常时介入。

Expand in small steps小步扩大覆盖面

One department, one owner, and one measurable target is a solid base for the next deployments.先锁定一个部门、一个负责人与一个量化目标，再复制到更多场景。

Reuse the runtime layer across projects复用运行时层，避免各项目重复接入

Shared runtime infrastructure keeps later integrations cheaper while outcomes stay tied to concrete business metrics.共享同一套运行时基础设施，后续接入成本更低，结果仍可落到具体业务指标上。

Product scenarios产品场景

These scenarios are the clearest places to apply the runtime after you understand how it sits next to your execution stack.

在了解运行时与现有执行栈如何分工之后，下列场景最能体现 harness 的用武之地。

Strong-fit scenarios契合度高的场景

Enterprise internal agent runtime企业内网智能体运行时
Coding-flow runtime with approvals and recovery带审批与恢复的编码类长流程
Agent-ops remediation workflows with parallel attempts and evidence export支持并行尝试与证据导出的 agent ops 修复流程
Protocol bridge runtime for ACP, A2A, AG-UI, and runtime MCP承接 ACP、A2A、AG-UI 与 runtime MCP 的协议桥接

Additional patterns更多适用形态

Governed multi-agent applications that need operator visibility需要运维可见性的受治理多智能体应用
Workspace-shaped apps that should keep one stable runtime contract across backend changes后端更替时仍要保持稳定运行时契约的工作区型应用
Teams that want reusable runtime infrastructure instead of per-project agent plumbing希望复用运行时基础设施、避免每个项目重复接入的团队

Minimal API精简 API

Grouped by lifecycle, invocation, events, inspection, and approvals.

按生命周期、调用、事件、查询与审批分组。

Feature snapshot: aligned to public contract v0.0.77 and implemented in the exported package API used below.

能力快照：与公开契约 v0.0.77 一致；下列示例来自当前导出的包 API。

// Import // 引入
import { createAgentHarness, deleteSession, getHealth, listApprovals, listRequests, listSessions, memorize, recall, request, resolveApproval, stop, subscribe } from "@botbotgo/agent-harness";

// Lifecycle — start and stop the runtime // 生命周期 — 启动与停止运行时
const runtime = await createAgentHarness(workspaceRoot);

// Invocation — request one execution against the workspace // 调用 — 对工作区发起一次运行
await request(runtime, { /* invocation */ });
await memorize(runtime, { /* durable memory candidates */ });
const memory = await recall(runtime, { query: "release policy" });
const learned = await listMemories(runtime, { scopes: ["workspace"] });
console.log(memory.items);

// Events — subscribe to runtime events (returns unsubscribe) // 事件 — 订阅运行时事件（返回取消订阅函数）
const unsubscribe = subscribe(runtime, (event) => {
console.log(event);
});

// Inspection — sessions, requests, approvals, health // 查询 — 会话、请求、审批与健康状态
const requests = await listRequests(runtime);
const sessions = await listSessions(runtime);
const approvals = await listApprovals(runtime);
const health = await getHealth(runtime);
console.log({ requests, sessions, approvals, health });

// Session cleanup — let users explicitly delete a completed session // 会话清理 — 允许用户显式删除已完成的 session
// if (sessions[0]?.status === "completed") await deleteSession(runtime, sessions[0].sessionId);

// Approvals — continue after a human-in-the-loop interrupt // 审批 — 人工介入中断后继续执行
// await resolveApproval(runtime, { sessionId, requestId, approvalId, decision: "approved", message: "ok" });

// Lifecycle — tear down // 生命周期 — 清理
await stop(runtime);
unsubscribe();

Documentation文档

Start with the chapter-based developer docs. They include a side-by-side comparison that shows where the harness sits relative to people-facing agent products, execution frameworks, and workflow tools.

从章节化开发文档开始，覆盖接入、配置、运行、排障、API 与协议说明；并列对比页帮助你在选型时理解 harness 与相关技术栈的差异。

Contact联系

A practical first step: read the docs to confirm the runtime model fits your product, then reach out if you want help with deployment or launch.

可以这样开始： 查阅文档，确认运行时模型与你的产品目标一致；需要部署或上线支持时，可通过下列方式联系。

info@easynet.world GitHub Issues Contributing贡献指南 Code of Conduct行为准则 Security安全说明 License许可协议