.NET+AI | Harness | Harness 正式发布，一行代码，生产级 Agent 就绪

Microsoft Agent Framework（MAF）也对 Harness 这一概念进行了系统实现。2026 年 7 月 22 日，微软在官方博客中宣布 Microsoft Agent Framework Harness 正式发布：开发者现在可以在 .NET 与 Python 中使用一个稳定的、batteries-included 的 Agent Harness，把模型、工具、记忆、计划、审批、上下文管理和遥测组合成一个可运行的生产级 Agent。

这也意味着，MAF Harness 从早期 v1.4 时代的实验性能力，走到了 v1.15 时代的正式发布阶段。它不再只是示例代码或 preview API，而是 Microsoft Agent Framework 里面向生产 Agent 的核心抽象之一。

参考资料：

The Microsoft Agent Framework Harness is now released
Agent Harnesses | Microsoft Learn
Step 6: Agent Harness | Microsoft Learn
Agent Harness in Agent Framework

一、为什么需要 Harness？

大模型本身只能生成文本。它可以回答问题、写计划、生成代码，但如果要让它真正“做事”，还需要一层外壳来处理这些问题：

它如何调用工具？
它如何拆解长期任务？
它如何记住已经做过什么？
它如何避免上下文爆掉？
它什么时候需要用户审批？
它失败后如何恢复？
它的执行过程如何观测？

这层外壳，就是 Agent Harness。

Microsoft Learn 对 Harness 的定义非常直接：Harness 是把语言模型变成实际 Agent 的脚手架；它驱动 Agent 的循环，执行模型请求的工具，管理历史与上下文，应用审批和安全策略，并推动任务持续完成。

换句话说：

Model 负责“想”，Harness 负责“让它能持续、可控、可观测地做”。

这也是为什么现在越来越多人讨论 “Agent = Model + Harness”。模型能力决定上限，Harness 工程决定落地质量。

二、MAF 里的 Harness 处在什么位置？

Microsoft Agent Framework 是微软面向生产级 AI Agent 的多语言框架，主要支持 .NET 与 Python，并可以接入 Microsoft Foundry、Azure OpenAI、OpenAI、Anthropic、Ollama 等模型生态。

从开发者视角看，MAF 里有三类重要抽象：

二、MAF 里的 Harness 处在什么位置？插图

Agents
：单个智能体，负责接收输入、调用工具、生成响应。
Harness
：一个开箱即用的“增强型 Agent 外壳”，适合长任务、自主任务、文件任务、研究任务。
Workflows
：显式编排多个 Agent 或函数，适合类型安全路由、检查点、人类介入等确定性流程。

所以 Harness 不是替代 Agent，也不是替代 Workflow。它更像是一个“生产级 Agent 默认套件”：当你不想从零手写工具循环、计划系统、上下文压缩、文件记忆、审批规则时，可以直接使用 Harness。

三、从 v1.4 实验能力到 v1.15 正式发布

MAF Harness 的演进很有代表性。

在早期 v1.4 阶段，社区已经开始用 Harness 组合 TodoProvider、AgentModeProvider、SubAgentsProvider、FileMemoryProvider 等组件来验证本地 LLM 场景。但当时它仍然不是正式发布 API，使用者需要接受后续 breaking changes 的风险。

随后，微软开始系统介绍 Agent Harness 的工程价值：它是模型推理连接真实执行的层，负责 shell、文件系统、审批流、长期上下文管理等能力。

到了后续版本，Python 与 .NET 逐步加入并完善 HarnessAgent / create_harness_agent，并推进 Todo、Agent Mode、Loop、File Memory、File Access、Skills、Tool Approval 等能力的组合。

最终，2026 年 7 月，微软正式宣布 Agent Framework Harness 发布。官方博客对它的描述是：一个稳定的、batteries-included 的 harness，内置 loop、planning、memory、context management、approvals、telemetry，能够把模型变成真正可以做事的 Agent。

这条演进线说明一件事：Harness 不再只是示例代码或实验模式，而是 MAF 的核心开发范式之一。

三、从 v1.4 实验能力到 v1.15 正式发布插图

四、代码入口：一行创建 Harness Agent

以 C# 为例，默认 Harness 的最小用法是：

Csharp code block

这段代码看起来只是把 chatClient 包了一层，但这层就是 Harness 的核心价值：它不是一个普通 chat wrapper，而是把 chat client 变成一个带有工具循环、计划状态、上下文管理、历史持久化、安全审批和可观测性的 Agent runtime。

官方文档也明确说明，Harness 是围绕 chat client 的 batteries-included agentic pipeline，内部在 .NET 中基于 ChatClientAgent，在 Python 中基于 Agent。

五、这行代码背后集成了什么？

可以把：

Csharp code block

理解成下面这组能力的组合：

Csharp code block

上面这段是“概念展开代码”，不是实际 API 链式调用。它的作用是说明：默认 Harness 把过去需要开发者手写的一整套 Agent 运行时拼装成了一个标准 Agent。

官方发布文章列出的默认能力包括 function invocation、per-service-call history persistence、compaction、todo 与 agent-mode providers、file memory、skills、web search、tool approval 和 telemetry。

五、这行代码背后集成了什么？（默认能力总览）插图

六、能力 1：自动 Tool Calling Loop

普通模型调用一般是：

Csharp code block

但 Agent 场景里，模型可能会说：“我需要先读文件、再分析、再写报告。”如果没有 Harness，你需要自己写循环：

Csharp code block

Harness 默认集成的 function invocation 就是帮你维护这个循环：模型请求工具，Harness 执行工具，工具结果进入上下文，模型继续推理，直到完成或达到迭代限制。

这件事看起来简单，但它是 Agent 与普通 Chatbot 的分界线：Chatbot 主要回答，Agent 可以行动。

七、能力 2：每次模型调用后持久化 History

长任务最怕中途断掉。例如 Agent 已经搜索了 8 个网页、读了 3 个文件、生成了中间计划，结果进程崩溃。如果没有 history persistence，前面的工作就丢了。

Harness 的 AgentSession 承担了跨轮状态容器的角色：

Csharp code block

这里第二次调用仍然传入同一个 session，所以 Harness 可以保留前一轮的计划、todo、history 等状态。

这也是为什么使用 Harness 时，不应该把每次调用都当成无状态请求。Harness 的价值很大一部分来自 session。

八、能力 3：TodoProvider，让 Agent 显式规划任务

没有 todo 的 Agent 很容易“边想边忘”。Harness 默认集成 TodoProvider，让 Agent 可以把复杂任务拆成工作项：

Code code block

这不是简单的 prompt 技巧，而是 Harness 提供的状态化能力。Agent 可以根据 todo 推进任务，也可以在任务过程中更新、完成或重排 todo。

对长任务来说，todo 的意义很大：它把模型的“隐式思考”变成了可跟踪的工作状态。

九、能力 4：AgentModeProvider，区分计划和执行

复杂任务通常有两个阶段：

Code code block

Harness 默认集成 AgentModeProvider，用于跟踪 plan / execute / custom mode。

这让 Agent 不只是连续聊天，而是可以在“规划”和“执行”之间切换，更接近真实工作流。尤其在需要审批、需要输出可解释计划、需要长期执行的场景里，mode tracking 很重要。

十、能力 5：Compaction，上下文自动压缩

长任务会不断把历史、工具结果、文件内容塞进上下文。没有压缩机制时，Agent 很容易超过模型 context window。

Harness 的 compaction 能力用于控制长工具循环中的上下文大小：

Csharp code block

这也是长任务 Agent 的关键工程问题之一。

如果没有 compaction，Agent 可能在任务还没完成时就因为上下文窗口溢出而失败；如果压缩策略太粗糙，又可能丢失关键事实。Harness 的意义在于，它把这个通用问题内置进运行时，而不是让每个开发者从零实现。

十一、能力 6：File Memory，保存跨轮笔记和产物

File memory 解决的是“Agent 工作记忆”的问题。比如 Agent 在调研过程中可以保存：

Code code block

它和聊天 history 不完全一样。

History 是对话过程。
File memory 更像 Agent 的工作笔记、草稿和中间产物。

对于研究、写作、代码修改、数据分析等任务，File memory 很有价值。它让 Agent 不必把所有东西都塞进上下文，而是可以把稳定中间产物落到文件里，在需要时再读取。

十二、能力 7：File Access，受控读写工作目录

文件访问适合数据分析、代码处理、报告生成等场景。例如：

Code code block

Agent 可以读取输入文件，分析后写出结果：

Code code block

不过 File Access 也是安全风险最高的能力之一。生产环境里，文件访问应该遵循几个原则：

只允许访问明确的 working directory。
高风险写操作需要审批。
不允许默认读取用户任意目录。
删除、覆盖、执行文件等操作要更严格。

可以在文章中用下面的概念代码说明：

Csharp code block

重点不是具体属性名，而是工程原则：Harness 可以提供文件工具，但文件访问必须被目录边界和审批策略约束。

十三、能力 8：Skills，按需加载领域能力

如果把所有领域知识都塞进 system prompt，会导致 prompt 越来越大、越来越难维护。

Harness 支持 Skills，让能力以文件包形式存在：

Code code block

Agent 可以在需要时发现并加载相关 skill，而不是一开始把所有知识放进上下文。

这类机制的好处是：

领域能力可以模块化维护。
不同 Agent 可以复用同一组 skills。
上下文更干净，不必预加载所有说明。
团队可以把最佳实践沉淀成可分发的能力包。

十四、能力 9：Web Search，服务支持时自动接入

研究类 Agent 需要获取当前信息。Harness 支持在底层推理服务提供 web search 能力时启用搜索：

Csharp code block

这里 Agent 可以先制定 todo，再调用 web search，再整理结果。

需要注意的是，Web Search 并不是所有模型和所有服务都天然支持。它通常依赖底层 inference service 的能力。因此文章中可以写成：当底层服务支持时，Harness 可以把 Web Search 纳入 Agent 的工具与 grounding 流程。

十五、能力 10：Tool Approval，安全审批

真实 Agent 不能随便执行所有工具。比如下面这些操作就应该有审批：

Code code block

Harness 集成 tool approval，可以把高风险工具调用交给人类确认，也可以对安全调用设置 “don’t ask again” 规则：

Code code block

这个能力非常关键，因为 Agent 的核心矛盾就是：

没有工具，它只是聊天机器人；工具太自由，它又可能变成风险源。

Tool approval 的作用，就是在自主性和安全性之间建立一个可配置的边界。

六/十五/十六：工具循环 + 审批 + 可观测性的闭环插图

十六、能力 11：Telemetry，内置可观测性

生产环境里的 Agent 不能是黑盒。你需要知道：

Code code block

Harness 默认集成 OpenTelemetry，方便把 Agent 的执行链路接入日志、trace 和监控系统。

这对生产环境非常重要。因为 Agent 系统的失败往往不是单点失败，而是模型、工具、上下文、权限、外部 API、用户输入共同作用后的链式问题。没有 telemetry，很难定位问题。

十七、Harness 与 Workflow 的区别

很多人会问：既然 MAF 已经有 Workflow，为什么还需要 Harness？

可以这样区分：

Harness 更适合开放式任务
：目标明确，但路径不完全确定，例如“帮我调研一个技术方案并输出报告”。
Workflow 更适合显式流程
：步骤、输入输出、路由规则相对确定，例如“审核申请 → 调用系统 → 人工确认 → 发送通知”。

换句话说，Harness 给 Agent 自主空间；Workflow 给系统确定性控制。

实际项目里，两者并不冲突。你可以把 Harness Agent 放进 Workflow，也可以让 Workflow 触发 Harness 去完成某个开放式子任务。

十八、适合哪些场景？

结合 Harness 的能力，它尤其适合四类应用。

1. 研究型 Agent

例如让 Agent 围绕一个主题生成计划、拆分 todo、搜索资料、整理摘要、写报告。这里需要计划、搜索、长期上下文、文件输出，正好是 Harness 的强项。

2. 文件 / 数据处理 Agent

例如读取一个目录里的 CSV、PDF、Markdown 或代码文件，分析后生成结果。File access、approval、history persistence 都很重要。

3. 编码助手或自动化工程 Agent

Coding Agent 的关键不是“会不会写代码”，而是能否安全读写文件、运行命令、保存中间状态、根据测试反馈迭代。Harness 正是在这个层面提供基础设施。

4. 企业领域助手

比如财务、法务、运营、客户支持场景。领域知识可以封装成 Skills，审批策略控制敏感操作，Telemetry 用于审计与优化。

十九、为什么这次正式发布重要？

MAF Harness 正式发布的意义，不只是多了一个 API，而是微软把 Agent 工程里的通用底座标准化了。

过去开发者做一个稍微复杂的 Agent，往往要自己拼这些东西：

工具调用循环
多步任务计划
上下文压缩
文件记忆
工具审批
会话持久化
可观测性
错误恢复
长任务 loop

这些都不是业务差异化能力，却很容易决定系统是否可用。

Harness 的价值就在于：把这些“每个 Agent 都需要、每个团队都容易重复造”的底层能力收敛成默认实现。

开发者只需要提供三件事：

Code code block

剩下的 agentic runtime 能力，由 Harness 默认处理。

二十、一个更完整的业务示例

假设我们要做一个“技术调研助手”，它可以搜索资料、生成 todo、保存笔记，并输出 Markdown 报告。业务代码大概可以写成这样：

Csharp code block

这段业务代码没有手写：

工具调用 loop
todo 状态
plan / execute 模式
history persistence
context compaction
file memory
approval
telemetry

但这些能力都可以由 Harness runtime 提供。

这正是 Harness 的核心价值：把通用 Agent 基础设施从业务代码里抽离出来。

二十一、一句话总结代码含义

可以用下面这句话总结：

Csharp code block

这行代码的意义不是“创建一个聊天机器人”，而是：

把一个普通 IChatClient 包装成一个生产级 Agent runtime：它默认具备工具调用循环、历史持久化、上下文压缩、todo 计划、plan/execute 模式、文件记忆、技能加载、搜索增强、工具审批和 OpenTelemetry 可观测性。开发者只需要补充模型、业务指令和领域工具，就可以开始构建长任务、自主执行型 Agent。

如果要写得更工程化，可以这样说：

Harness 把通用 Agent 基础设施从业务代码里抽离出来，让开发者不用重复手写 loop、memory、planning、approval 和 telemetry，而是把精力放在业务工具和领域能力上。

结语：Agent 开发正在进入 Harness Engineering 阶段

MAF Harness 的发布说明，Agent 开发正在从“拼模型调用”进入“设计运行系统”的阶段。

早期我们关心的是：

用哪个模型？Prompt 怎么写？工具怎么接？

现在更关键的问题变成：

Agent 如何持续推进任务？如何记忆？如何压缩上下文？如何安全行动？如何观测？如何失败恢复？如何让人类只在关键点介入？

这些问题都属于 Harness Engineering。

所以，MAF Harness 的价值不只是让微软生态里的 Agent 更容易写，而是给了开发者一个清晰信号：生产级 Agent 的竞争点，正在从单次推理能力，转向模型外部运行系统的工程质量。

从 v1.4 实验版本到 v1.15 正式发布，MAF Harness 走过的是一条典型的 Agent 基础设施成熟路线：先把模式跑通，再把组件拆稳，最后把通用能力封装成默认运行时。

对开发者来说，接下来写 Agent 时不妨换一个思路：

不要先问“这个模型能不能做？”先问“我有没有给它一个足够好的 Harness，让它能安全、持续、可观测地做？”

引入地址

龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

大模型安全实战】智能体安全的攻防二元性：同一种能力，为什么既是防线也是攻击面？（第4期）

龙虾开发者社区

SparkSQL 之 Hive On Spark 原理分析

龙虾开发者社区

2026大厂AI Agent面试深度复盘：从“会背概念“到“能扛生产“的范式跃迁

2026年AI Agent面试核心要点摘要（147字）大厂AI Agent面试已从概念背诵转向工程实践考核，重点考察：1）理解Agent与Chatbot的本质差异在于闭环行动能力；2）掌握ReAct循环、记忆分层设计（工作/短期/长期记忆）及优化策略；3）熟悉MCP协议对工具调用的标准化改进及安全风险；4）具备异常处理、性能优化的工程能力。面试官更关注候选人在非确定性系统中构建确定性保障的能力，