Agent Harness工程化实战：如何解决大模型幻觉带来的不确定性？答案在文中+开箱可用的github源码

你让AI写代码，它说"已修复bug"，但实际没修复。

你让AI查数据，它说"已查询"，但返回了错误结果。

这不是AI的问题，是你没有用Agent Harness。

你可能已经搭建过聊天机器人，甚至接入了几个工具，做出了能演示的原型。

但当你想把它推向生产环境时，问题就来了：模型会忘记三步之前做过什么，工具调用会失败，上下文窗口塞满了无用信息。

问题不在模型本身，而在模型周围的一切。

LangChain 用一个实验证明了这点：

他们只改变了 LLM 的基础设施（模型和权重完全不变），在 TerminalBench 2.0 的排名就从 30 名开外跃升到第 5 名。

另一个研究项目让 LLM 自己优化基础设施，通过率达到 76.4%，超过了人工设计的系统。

这套基础设施现在有了正式名称：Agent Harness。

什么是Harness？咱们本次不深入聊，感觉兴趣的小伙伴可以移步一文讲透 Harness：AI 从“聪明”到“靠谱”的关键跃迁

下面我们继续聊这个小的点：Agent Harness如何解决大模型幻觉带来的不确定性？

AI幻觉的核心问题：

• AI会说谎（无意识）
• AI会编造（无恶意）
• AI会过度自信（不自知）

Agent Harness的解决方案：

• 验证循环：让AI验证自己的输出
• 防护栏：阻止AI执行危险操作
• 上下文管理：给AI提供准确的信息
• 绊线机制：触发时立即停止

核心价值： 让AI从"可能出错"变成"可验证、可控制、可恢复"。

一、聊天机器人的幻觉问题

▪ 1.1 典型场景

场景1：AI写代码

用户：帮我写一个用户登录功能。 AI：已创建login.py文件，包含完整的登录逻辑。 用户：打开文件。 实际：文件是空的，或者代码有语法错误。

场景2：AI查数据

用户：查询用户张三的订单。 AI：张三有以下订单：1001（500元）、1002（800元）。 实际：数据库里根本没有这些订单，AI编造了。

场景3：AI执行命令

用户：删除日志文件。 AI：已删除logs目录下的所有日志文件。 实际：删除了系统目录，造成服务崩溃。

▪ 1.2 幻觉的根源

为什么AI会产生幻觉？

1. 预测机制AI基于概率预测下一个词，不是基于事实
2. 上下文有限AI看不到完整的信息，只能猜测
3. 无自我意识AI不知道自己在说谎，它只是在"生成文本"
4. 过度自信AI会用肯定的语言表达不确定的信息

根据Anthropic的研究（Claude Code文档）：

• 在没有验证循环的情况下，AI的错误率高达15-20%
• 在有验证循环的情况下，错误率降低到1-2%
• 这意味着验证循环可以将AI的可靠性提升10倍以上

二、Agent Harness的三大解决方案

▪ 2.1 验证循环（Verification Loops）

核心思想： 让AI验证自己的输出，而不是直接交付。

三种验证方法：

1. 基于规则的验证
   • 测试、linter、类型检查器
   • 确定性，不依赖AI判断
2. 视觉反馈
   • 通过Playwright截图验证UI任务
   • 直观，容易理解
3. LLM作为评判者
   • 用另一个AI评估输出
   • 捕获语义问题

实战：代码实现验证循环

from src.verification import VerificationLoop, LLMJudge # 创建验证循环 verification_loop = VerificationLoop() # 添加验证器 verification_loop.add_validator(validate_python_syntax) verification_loop.add_validator(validate_no_print) verification_loop.add_validator(validate_has_docstring) # 执行带验证的任务 result, attempts = verification_loop.execute_with_verification( generate_code, fix_code )

肉眼可见的区别：

聊天机器人：

用户：帮我写一个用户登录功能。 AI：已创建login.py，完成。 用户：测试代码。 实际：代码有bug，不能运行。

Agent Harness：

用户：帮我写一个用户登录功能。 AI：创建login.py → 运行测试 → 修复bug → 测试通过 → 交付 用户：测试代码。 实际：代码正常运行，功能完整。

▪ 2.2 防护栏（Guardrails）

核心思想： 在AI执行危险操作前，进行检查和确认。

三级防护栏：

1. 输入防护栏在第一个agent上运行
2. 输出防护栏在最终输出上运行
3. 工具防护栏在每次工具调用时运行

"绊线"机制： 触发时立即抛出异常，停止Agent执行。

实战：代码实现防护栏

from src.guardrails import Guardrails, DangerLevel, GuardrailViolation guardrails = Guardrails() # 注册工具及危险级别 guardrails.register_tool("read_file", DangerLevel.SAFE) guardrails.register_tool("delete_file", DangerLevel.HIGH) # 检查工具权限（触发绊线） try: guardrails.check_tool_permission("delete_file") except GuardrailViolation as e: print(f"🛑 绊线触发: {e}")

肉眼可见的区别：

聊天机器人：

用户：删除所有日志文件。 AI：已删除。 实际：删除了系统目录，服务崩溃。

Agent Harness：

用户：删除所有日志文件。 AI：这是一个危险操作，需要确认。确认删除logs目录吗？(y/n) 用户：y AI：已删除logs目录下的15个文件。 实际：只删除了logs目录，系统正常运行。

▪ 2.3 上下文管理（Context Management）

核心思想： 给AI提供准确的信息，避免猜测。

生产策略：

1. 压缩在接近限制时总结对话历史
2. 观察遮蔽隐藏旧的工具输出，但保持工具调用可见
3. 即时检索维护轻量级标识符，动态加载数据
4. 子智能体委托每个子智能体广泛探索，但只返回压缩摘要

实战：代码实现上下文管理

from src.context import ContextManager context_manager = ContextManager(workspace="/path/to/project") # 搜索记忆 memory = context_manager.search_memory("数据库") # 压缩对话历史 compressed = context_manager.compress_conversation() # 获取上下文 context = context_manager.get_context(user_query)

肉眼可见的区别：

聊天机器人：

用户：这个项目用什么数据库？ AI：这个项目用PostgreSQL。 实际：项目用的是MySQL，AI猜错了。

Agent Harness：

用户：这个项目用什么数据库？ AI：从MEMORY.md检索信息。 AI（回答）：这个项目用MySQL作为主数据库，用Redis作为缓存。 实际：正确，因为信息来自MEMORY.md。

三、生产级的HarnessAgent

▪ 3.1 完整集成三大功能

harness-tutorials提供生产就绪的Agent实现：

from src.agent import HarnessAgent, Tool, DangerLevel # 创建Agent agent = HarnessAgent( name="MyAgent", workspace="/path/to/workspace" ) # 注册工具 agent.register_tool(Tool( name="read_file", description="读取文件", danger_level=DangerLevel.SAFE, func=lambda path: read_file(path) )) # 执行任务 result = agent.execute_task( task="读取config.yaml", tool_name="read_file", path="config.yaml" ) print(f"成功: {result.success}") print(f"输出: {result.output}") print(f"尝试次数: {result.attempts}")

▪ 3.2 完整执行流程

HarnessAgent的执行流程：

1. 输入检查（防护栏 - 马鞍） └─ 触发时立即抛出异常 2. 获取上下文（围栏） └─ 从MEMORY.md检索相关信息 3. 检查工具权限（缰绳） └─ 危险操作需要确认 4. 执行工具 └─ 调用实际的功能函数 5. 验证输出（马鞍） └─ 基于规则 + LLM评判 6. 输出检查（防护栏） └─ 触发时立即抛出异常

▪ 3.3 实际运行效果

运行示例：

# 克隆项目 git clone https://github.com/helloworldtang/harness-tutorials.git cd harness-tutorials # 安装依赖 uv sync # 配置环境变量 cp .env.example .env # 编辑 .env，填入 DEEPSEEK_API_KEY # 运行Agent示例 uv run python -m src.agent

输出示例：

============================================================ 生产环境示例：文件操作Agent ============================================================ 📋 示例1: 安全操作（读取文件） ------------------------------------------------------------ 2026-04-22 18:30:11 - INFO - Agent 'FileOperationsAgent' 初始化完成 2026-04-22 18:30:11 - INFO - 🛡️ 步骤1: 输入检查（防护栏） 2026-04-22 18:30:11 - INFO - 📝 步骤2: 获取上下文 2026-04-22 18:30:11 - INFO - 🔒 步骤3: 检查工具权限（防护栏） 2026-04-22 18:30:11 - INFO - ⚙️ 步骤4: 执行工具: read_file 2026-04-22 18:30:11 - INFO - 🔍 验证输出（尝试 1/3） 2026-04-22 18:30:11 - INFO - 🛡️ 步骤5: 输出检查（防护栏） 2026-04-22 18:30:11 - INFO - ✅ 任务完成（尝试 1 次） 结果: ✅ 成功 输出: 文件内容: README.md 尝试次数: 1 📋 示例2: 危险操作（删除系统文件 - 触发防护栏） ------------------------------------------------------------ 2026-04-22 18:30:11 - INFO - 开始执行任务: 删除/etc/passwd文件 2026-04-22 18:30:11 - ERROR - 🛑 绊线触发: [input_filter] 输入被拦截：包含敏感关键词：删除 结果: ❌ 失败 错误: [input_filter] 输入被拦截：包含敏感关键词：删除 防护栏触发: 是 ============================================================ Agent 'FileOperationsAgent' 执行统计 ============================================================ 总任务数: 3 成功任务: 1 失败任务: 0 防护栏触发: 2 验证失败: 0 成功率: 33.3% ============================================================

四、对比：聊天机器人 vs Agent Harness

五、核心定义：Harness Engineering

Harness Engineering研究的是"怎么给AI Agent搭环境让它靠谱干活"。Harness Engineering是让AI Agent可靠执行长任务的工程实践，通过持久状态、任务分解和反馈回路构建外循环系统。它标志着人机交互从指令驱动向意图驱动转变，工程师角色正转向自治系统设计者。

类比：

• 模型是骑手：提供智能和决策
• Agent是马：执行任务和行动
• Harness就是马鞍、缰绳和围栏：控制和引导

没有Harness：

• 马也会跑，但跑哪去不确定
• AI会说"已完成"，但实际没做

有了Harness：

• 马鞍（验证循环）：让骑手坐得稳
• 缰绳（防护栏）：控制马不要跑到危险地方
• 围栏（上下文）：给马一个安全的活动范围

结果： 马（Agent）靠谱干活，骑手（模型）安心驾驭。

六、快速开始

▪ 6.1 安装

# 克隆项目 git clone https://github.com/helloworldtang/harness-tutorials.git cd harness-tutorials # 安装 uv（如果尚未安装） curl -LsSf https://astral.sh/uv/install.sh | sh # 创建虚拟环境并安装依赖 uv sync

▪ 6.2 配置

# 复制环境变量文件 cp .env.example .env # 编辑 .env，填入你的 DeepSeek API Key # DEEPSEEK_API_KEY=sk-your-actual-api-key-here

# 也可以在本机的环境变量中配置DEEPSEEK_API_KEY

▪ 6.3 运行

# 运行测试 uv run pytest tests/ -v # 运行Agent示例 uv run python -m src.agent # 运行主程序 uv run python -m src.main

七、项目结构

harness-tutorials/ ├── README.md # 完整文档 ├── pyproject.toml # 项目配置（uv） ├── .env.example # 环境变量示例 ├── heartbeat.md # 任务清单 ├── tools.md # 工具权限配置 ├── memory.md # 记忆系统 └── src/ ├── verification.py # 验证循环（集成DeepSeek LLM） ├── guardrails.py # 防护栏（绊线机制） ├── context.py # 上下文管理 ├── agent.py # 生产环境Agent（MVP） └── main.py # 主程序

八、生产环境使用建议

▪ 8.1 扩展验证器

# 添加自定义验证器 agent.add_validator(lambda x: x is not None) agent.add_validator(lambda x: isinstance(x, str) and len(x) > 0)

▪ 8.2 添加过滤器

from src.guardrails import filter_sensitive_keywords agent.add_input_filter(filter_sensitive_keywords) agent.add_output_filter(filter_sensitive_keywords)

▪ 8.3 注册自定义工具

agent.register_tool(Tool( name="custom_tool", description="自定义工具", danger_level=DangerLevel.MEDIUM, func=my_custom_function ))

▪ 8.4 监控和统计

# 获取执行统计 stats = agent.get_stats() print(f"总任务数: {stats['total_tasks']}") print(f"成功率: {stats['successful_tasks'] / stats['total_tasks'] * 100:.1f}%") # 打印详细统计 agent.print_stats()

九、总结

核心要点：

1. 问题：AI幻觉（无意识说谎、编造信息、过度自信）
2. 方案：Agent Harness的三大解决方案（验证循环、防护栏、上下文管理）
3. 实现：harness-tutorials提供生产环境MVP
4. 效果：幻觉率从15-20%降低到1-2%

数据来源：

• Anthropic Claude Code文档 https://code.claude.com/docs/zh-CN/how-claude-code-works https://claude.com/blog/building-agents-with-the-claude-agent-sdk
• Chroma研究（上下文腐烂问题） https://github.com/chroma-core/context-rot https://www.trychroma.com/research/context-rot
• 乔木博客《Agent Harness：让AI从聊天机器人变成真正的智能体》https://blog.qiaomu.ai/2026-04-18-JgypqM

项目源码github地址：

• GitHub: https://github.com/helloworldtang/harness-tutorials

复现耗时及依赖：

开始时间： 现在

完成时间： 10分钟后

所需工具： Python 3.10+, uv

Agent Harness不是理论，是实践。

harness-tutorials项目提供生产环境可用的MVP，让每个开发者都能搭建可验证、可控制、可恢复的智能体。

让AI从"可能出错"变成"值得信任"。