Blog
Agent Harness 是什么？一次说清运行时、Session 与权限边界
Agent Harness 是把大模型变成可用 Agent 的运行时层。本文说明它到底负责什么、和 Agent 框架及 MCP 的区别，以及为什么进入生产环境后要求会突然变高。
Agent Harness 是把大模型变成「可用 Agent」的那一层运行时。
模型负责推理，Harness 负责其他所有事：跑执行循环（调用模型、执行工具、把结果喂回去）、维护 Session 状态、给 Agent 一块可操作的工作区、装配它能调用的工具，并守住权限与沙箱边界。
理解了这条分界线，就能解释一个很常见的现象：Agent 一旦离开 demo 阶段，出问题的地方往往不是推理，而是运行时。上下文在两次运行之间丢了；工具调用碰到了不该碰的东西；没人能还原当时发生了什么；Agent 没法接着昨天的工作往下做。
容易混淆的四层
这几个词经常被混着用，但它们处在不同层，职责也不同。
| 层 | 它是什么 | 它不负责什么 |
|---|---|---|
| 模型 | 推理引擎 | 没有记忆、没有工具、不能持久化 |
| 框架 | 用来表达 Agent 逻辑的库 | 不管执行、状态和治理 |
| Harness | 真正执行并约束 Agent 的运行时 | 不决定你产品的交互界面 |
| 协议（MCP） | 连接工具与数据的约定 | 它不是运行时，也不管 Session |
一个简单的判断方法：把它删掉，什么会坏？
删掉模型，没东西会推理。删掉框架，你要多写些代码，但 Agent 还能跑。删掉 Harness，Agent 在两次请求之间就不存在了，因为持有它状态、工具和权限的东西没了。
Harness 到底负责什么
清单不长，但每一项都缺不得：
- 执行循环：调用模型、解析工具调用、执行、把结果喂回，直到任务完成或触到上限。
- Session 状态：对话、工作上下文，以及继续、分叉、重放一个 Session 的能力，而不是每次从头开始。
- Workspace：Agent 能操作的文件、目录与 Shell。没有边界清晰的工作区，Agent 做不了真活。
- 工具与 Plugin：Agent 实际能调用的东西，且是显式装配的，不是碰巧发现的。
- 记忆：什么能跨 Session 存活，以及后续怎么检索出来。
- 权限与沙箱：哪些动作允许、哪些需要审批、硬边界画在哪里。
- 服务：模型访问、身份、存储，以及 Agent 需要的外部能力。
- 用量与成本：调了哪个模型、花了多少 token、由谁买单。
- 可观测性：日志、链路与产物，要足以回答「它做了什么，为什么这么做」。
注意这里面几乎没有「提示词」的份量。Harness 的工作主要是系统工程：进程边界、状态机、权限、成本核算。
和 Agent 框架的区别
框架帮你描述一个 Agent，Harness 帮你运行一个 Agent。
框架擅长编排：链、图、工具定义、提示模板。但它是库，所以进程、持久化、权限模型和部署方式仍然归你的应用管。
当有人说「Agent 在 notebook 里好好的，上生产就不行」，缺的通常就是这一层。库在履行自己的职责，只是没有任何东西在履行运行时的职责。
和 MCP 的关系
MCP（Model Context Protocol）是连接标准。它把一个具体问题回答得很好：Agent 如何以可预期的方式访问某个工具或数据源？
这很有价值，但它和 Harness 不是同一件事。MCP 定义的是 Agent 边缘的契约；Harness 持有的是 Agent 本身：它的循环、Session、Workspace、权限与计费。
两者是组合关系，不是竞争关系。Harness 可以把 MCP server 作为工具暴露给 Agent。但 MCP 本身不会告诉你：哪个 Session 在什么成本下、用谁的凭证调用了哪个工具。那是 Harness 的领地。
为什么进入生产后要求会突然变高
一旦有真实用户依赖这个 Agent，四个要求会立刻出现。
可续跑。 demo 在一个进程里跑九十秒。真实 Agent 要跨重启、跨部署跑几周。状态必须活得比进程久，Session 也就必须是持久化对象，而不是内存里的便利结构。
边界。 只给自己用的时候，工具权限放开无所谓。面对真实用户，你必须能明确回答：Agent 可以碰什么、什么需要人工审批、沙箱边缘在哪里。
多个产品共用一套后端。 多数团队要交付的不是一个 Agent，而是控制台、扩展、API 和内部工具，它们都需要同一套模型、账号与用量记录。每个入口各重建一遍，正是 Agent 项目悄悄死掉的方式。
成本可见。 token 开销是真实的成本项。如果用量无法归因到某个用户、产品或 Session，你就没法定价、限流或排查。
这些都不是模型问题，全部是 Harness 问题。
Downcity 与这些职责的对应关系
Downcity 是一套开源 Agent Harness，以及让它可交付的配套 Kit。职责到组件的映射是刻意的，基本一一对应：
| Harness 职责 | Downcity 组件 |
|---|---|
| 执行循环、Session、Workspace | Agent Harness 与 Agent 运行时 |
| 本地 Agent 宿主与请求转发 | City |
| 模型目录、Service 路由、身份 | Federation |
| 把 Agent 嵌进你自己的应用 | Agent SDK |
| 工具、记忆、Shell、任务 | Agent Plugins |
| 用量、Credits 与支付 | 账号与支付 |
| 面向 Agent 的 UI 模式 | UI SDK |
有两个设计选择值得单独指出，因为它们决定了其他一切。
第一，能力显式装配。由调用方决定这个 Agent 挂哪些 Plugin 和工具，而不是依赖平台自动组装。显式装配是权限可审计的前提。
第二，产品边界与运行时分离。产品负责用户体验；Agent 在明确边界内执行；运行时负责那些被反复重建的基础设施：模型、工具、任务、记忆、权限、用量、计费与可观测性。更完整的论证写在白皮书里。
常见问题
Agent Harness 就是 Agent 框架吗？ 不是。框架是用来描述 Agent 逻辑的库；Harness 是执行它、持有它状态、约束它能做什么的运行时。多数团队最终两者都需要。
已经用了 MCP，还需要 Harness 吗？ 如果 Agent 只是偶尔调几个工具，MCP 可能够用。一旦你需要可续跑的 Session、权限控制、成本归因，或者多个产品共用一个后端，你就需要一个运行时，那就是 Harness。
Harness 只适用于编码 Agent 吗？ 不是。编码 Agent 让这个词流行，是因为它一次性压满了所有运行时要求：长 Session、文件读写、Shell 执行、审批。研究、运营、客服类 Agent 面对的是同一组要求。
可以自己实现一个吗？ 可以，很多团队也是这么起步的。真实的代价是：你最终会把 Session 持久化、沙箱、权限校验、用量核算和多入口访问重新实现一遍。如果不想从零开始，Downcity 是开源的。
下一步
想先看到 Harness 跑起来再读理论，可以直接安装 CLI 并启动第一个 Agent，几分钟内就能拿到一个真实的 Session、Workspace 和工具边界。
想先理解架构，建议读生产级 Agent 白皮书，它解释了 Harness 这一层为什么存在，以及边界应该画在哪里。如果需要更细的产品文档，可以从文档首页进入。