三分钟心智模型
agent-harness 不是新的 agent framework。现有执行后端继续负责执行语义，`agent-harness` 负责把这些能力接成一套可以运行、检查和恢复的应用运行时。
最短定义
你负责 workspace、agents、tools 和产品行为；`agent-harness` 负责把它们接成一套可上线的运行时。
什么时候适合用
如果你缺的是运行时层，而不是再多一个 agent loop，那么它通常适合你。
适合
你需要审批、持久化记录、重启恢复、排队或运行检查能力。
不适合
你只需要一次短生命周期调用，不关心审批、持久化和后续运行维护。
工作区结构与源码分层
应用侧按 workspace 形状装配；YAML 在 config/** 下会被递归发现，下面是与 README 一致的推荐目录结构。
your-workspace/
config/
agent-context.md
runtime/
workspace.yaml
runtime-memory.yaml
catalogs/
models.yaml
embedding-models.yaml
vector-stores.yaml
stores.yaml
backends.yaml
tools.yaml
mcp.yaml
agents/
direct.yaml
orchestra.yaml
resources/
package.json
tools/
skills/维护本开源仓库时
若你改的是 agent-harness 包本身，请把实现放在仓库根的 src/、测试放在 test/，不要与上面的应用工作区混为一谈。
第一次受治理运行
- 安装包并建好标准工作区结构。
- 先在 YAML 里定义 models、stores、tools、MCP 和 agents。
- 用
createAgentHarness(...)启动 runtime。 - 用
request(...)发起任务，用subscribe(...)观察执行过程。 - 用 inspection APIs 查看 requests、sessions、approvals 和 health。
import { createAgentHarness, request, listSessions, stop } from "@botbotgo/agent-harness";
const runtime = await createAgentHarness(process.cwd());
const result = await request(runtime, {
agentId: "orchestra",
input: "Review this repository and propose the next runtime improvement.",
});
console.log(result.output);
console.log(await listSessions(runtime));
await stop(runtime);一开始先决定这三件事
先选 backend
想要更高层的执行语义、少写应用侧编排，优先用 backend: deepagent。如果只是较轻量的 direct-response 流程，或者工作区明确需要更轻的后端形态，再用 backend: langchain-v1。
让运行时负责运行时问题
审批、恢复、检查和排队，尽量交给运行时来处理，不要散落在 prompt 约定里。
以公开发布说明为准
README、开发文档与 RELEASE_NOTES.md 描述已发布行为；集成、升级或排查差异时，请优先对照这些材料。
下一步读什么
完成起步之后，建议先读“应用模型”，了解运行时会长期保持稳定的对象和接口。