Harness Agent架构解析：构建安全可控的AI智能体基础设施

1. 从“工具人”到“智能体”：为什么我们需要Harness Agent？

如果你最近在AI编程领域摸爬滚打，大概率会频繁听到“Agent”这个词。从AutoGPT到Devin，再到各种雨后春笋般冒出的AI编程助手，它们都在试图扮演一个能自主理解任务、拆解步骤、调用工具并最终完成目标的“智能体”。但当你真正上手去用，或者想自己动手构建一个时，往往会发现一个尴尬的现实：想法很丰满，但实现起来，核心的Agent逻辑总是被一堆繁琐的“家务事”所淹没。

这些“家务事”包括但不限于：如何安全、高效地调用外部工具（比如执行Shell命令、读写文件、调用API）？如何管理Agent思考过程中的状态（记忆、上下文、中间结果）？如何设计一个稳定、可扩展的执行循环（Agent Loop），让AI能一步步推进而不是卡死或跑偏？如何优雅地处理错误、进行重试和回滚？这些问题，每一个都足以让开发者从“AI魔法师”变回“调参工程师”，在基础设施的泥潭里挣扎。

这，正是“Harness Agent”架构试图解决的核心痛点。它不是一个全新的、要取代现有LLM或Agent的“超级AI”，而是一套包裹在AI Agent核心推理逻辑之外的基础设施层。你可以把它想象成一个高度专业化的“制片人”或“舞台总监”。核心的AI模型（比如Claude、GPT）是才华横溢的“主演”，它负责理解剧本（任务）、即兴发挥（推理）。而Harness Agent则是那个确保演出顺利进行的人：它搭建好舞台（执行环境），准备好道具（工具系统），安排好灯光和音效（状态管理与流程控制），并在演员忘词或走错位时（错误处理）及时补救，最终引导整场演出（任务）完美落幕。

所以，当我们谈论“Claude Code Harness Agent”时，我们讨论的绝不仅仅是“如何用Claude写代码”。我们深入探讨的，是如何为像Claude Code这样强大的“代码主演”，构建一个健壮、可靠、可扩展的“制片体系”，让它能从简单的代码补全，进化成能真正理解复杂需求、自主规划并执行多步骤编程任务的智能体。这套架构，是连接当前AI惊人潜力与未来真正自动化生产之间的关键桥梁。

2. 庖丁解牛：Harness Agent 的核心组件与职责边界

要理解Harness Agent，我们不能把它看成一个黑盒，而必须拆开看它的内部构造。一个典型的、设计良好的Harness Agent架构通常由几个相互协作的核心组件构成，它们各司其职，共同支撑起智能体的“思考-行动”循环。

2.1 大脑与指挥官：LLM 与 Agent Core

这是整个系统的“灵魂”。LLM（大语言模型，如Claude 3、GPT-4）负责最核心的认知功能：理解自然语言指令、进行逻辑推理、规划任务步骤、生成代码或决策。而Agent Core则是围绕LLM的一层薄薄的封装，它定义了与LLM交互的固定模式，比如如何构建提示词（Prompt）、如何解析LLM的响应（通常期望其输出结构化的JSON，包含“思考”和“行动”指令）。

关键设计点：Agent Core并不处理具体的工具调用或状态管理，它只负责与LLM“对话”，并将LLM输出的结构化指令（例如{"action": "execute_shell", "args": {"command": "ls -la"}}）传递给下一个环节。它的职责单一而清晰。

2.2 工具箱与执行器：Tool System

这是智能体的“手”和“脚”。Tool System定义了一组Agent可以调用的操作集合。每个工具（Tool）都是一个独立的函数，有明确的名称、描述、输入参数格式和实现逻辑。常见的工具包括：

• execute_shell: 执行Shell命令。
• read_file: 读取文件内容。
• write_file: 写入或修改文件。
• search_web: 联网搜索（需额外权限）。
• call_api: 调用特定的外部API。

Harness层的核心价值在这里凸显：一个基础的Agent实现可能直接让LLM输出命令字符串，然后由系统执行，这带来了巨大的安全风险（例如rm -rf /）。Harness中的Tool System实现了沙箱化和权限控制。它会：

1. 验证与路由：检查Agent Core传来的动作指令是否在允许的工具列表内。
2. 参数校验与净化：对输入参数进行严格的检查和过滤，防止注入攻击。
3. 安全执行：在受控的环境（如Docker容器、权限受限的进程）中运行危险操作。
4. 标准化输出：将工具执行的结果（成功后的输出或失败时的错误信息）格式化为统一的格式，返回给状态管理器。

2.3 记忆与舞台监督：State Management

Agent在执行任务时不是失忆的，它需要记住之前做了什么、得到了什么结果、当前任务进展到哪一步。State Management就是它的“工作记忆”和“舞台监督脚本”。

它主要管理两类状态：

1. 会话状态（Session State）：包括整个任务的原始目标、历史对话记录（LLM的输入输出）、已执行工具的历史及结果。这为LLM提供了完整的上下文，使其能进行连贯的思考。
2. 控制状态（Control State）：当前Agent Loop处于哪个阶段（思考？执行？等待用户输入？），是否有错误发生，重试计数是多少等。这决定了流程的走向。

一个设计良好的状态管理器还应该支持状态持久化，这样即使Agent进程中断，重启后也能从断点恢复，这对于执行耗时长的复杂任务至关重要。

2.4 流程引擎：Agent Loop

这是将所有组件串联起来的“总控循环”，也是Harness架构的“骨架”。一个典型的Agent Loop遵循经典的“思考（Think）- 行动（Act）- 观察（Observe）”模式，具体步骤如下：

1. 初始化：接收用户任务，初始化状态管理器。
2. 循环开始： a.思考阶段（Think）：Agent Core将当前状态（任务描述+历史记录+可用工具列表）组织成提示词，发送给LLM。LLM经过推理，输出一个结构化的“下一步行动”决定。 b.解析与验证：Agent Core解析LLM的输出。如果输出是“最终答案”，则跳出循环，返回结果。如果输出是“调用工具”，则进入行动阶段。 c.行动阶段（Act）：Tool System接收行动指令，进行安全校验后，在受控环境中执行对应的工具。 d.观察阶段（Observe）：Tool System将执行结果（成功或失败）标准化。State Management将这个结果作为新的一条“观察”记录，更新到会话历史中。
3. 循环继续：更新后的状态被送入下一轮“思考”阶段，如此循环，直到LLM认为任务完成或主动终止。

这个循环的健壮性由Harness保障，例如，当LLM输出无法解析的指令时，Harness可以注入一条系统提示，要求LLM纠正；当工具执行失败时，Harness可以将错误信息反馈给LLM，让其尝试其他方案。

2.5 安全与可观测性：外围保障层

这是Harness的“安保系统”和“仪表盘”。

• 安全沙箱：对于代码执行、Shell命令等高风险操作，必须运行在隔离的容器或虚拟机中，严格限制网络、文件系统访问权限。
• 权限模型：定义不同级别的工具访问权限，例如，初级Agent可能只能读文件，高级Agent才能写文件和执行命令。
• 日志与监控：详细记录每一个Loop的输入输出、工具调用详情、耗时和资源消耗。这是调试复杂Agent行为和进行性能优化的基础。
• 人机交互（HCI）：提供机制让人类在关键节点进行审核、确认或干预，实现“人在环路”（Human-in-the-loop），这是确保复杂任务可靠性的最终安全阀。

通过以上拆解，我们可以看到，Harness Agent架构的本质，是将AI智能体开发中那些非核心但至关重要的工程问题——安全、可靠、状态、流程——抽象成一套标准化、可复用的基础设施。它让研究者能更专注于提升“主演”（LLM）的演技，而无需为舞台的每一颗螺丝钉操心。

3. 实战推演：构建一个简易的“代码生成与执行”Harness Agent

理论说得再多，不如动手搭一个。让我们设想一个具体的场景：构建一个能接受自然语言描述，自动编写Python脚本并执行验证的Harness Agent。我们将基于上述架构，勾勒出关键的实现步骤和设计决策。

3.1 定义工具集：给Agent戴上“手套”

首先，我们需要定义Agent能使用的工具。为了安全和聚焦，我们只定义三个核心工具：

# tools.py import subprocess import sys import os from typing import Dict, Any import tempfile class ToolSystem: def __init__(self, workspace_dir: str = "./workspace"): self.workspace = workspace_dir os.makedirs(self.workspace, exist_ok=True) def execute_python_code(self, code: str) -> Dict[str, Any]: """在安全隔离的环境中执行一段Python代码，并返回结果或错误。""" # 使用临时文件，避免代码注入风险 with tempfile.NamedTemporaryFile(mode='w', suffix='.py', dir=self.workspace, delete=False) as f: f.write(code) temp_file_path = f.name try: # 使用subprocess在子进程中运行，可以超时控制 result = subprocess.run( [sys.executable, temp_file_path], capture_output=True, text=True, timeout=30, # 设置超时，防止死循环 cwd=self.workspace ) # 清理临时文件 os.unlink(temp_file_path) return { "success": result.returncode == 0, "stdout": result.stdout, "stderr": result.stderr, "returncode": result.returncode } except subprocess.TimeoutExpired: os.unlink(temp_file_path) return {"success": False, "error": "Execution timed out after 30 seconds."} except Exception as e: return {"success": False, "error": f"Execution failed: {str(e)}"} def read_file(self, filepath: str) -> Dict[str, Any]: """读取工作空间内指定文件的内容。""" full_path = os.path.join(self.workspace, filepath) if not os.path.exists(full_path): return {"success": False, "error": f"File not found: {filepath}"} if not os.path.isfile(full_path): return {"success": False, "error": f"Path is not a file: {filepath}"} try: with open(full_path, 'r', encoding='utf-8') as f: content = f.read() return {"success": True, "content": content} except Exception as e: return {"success": False, "error": f"Failed to read file: {str(e)}"} def write_file(self, filepath: str, content: str) -> Dict[str, Any]: """在工作空间内创建或覆盖一个文件。""" full_path = os.path.join(self.workspace, filepath) # 简单安全校验：防止路径穿越攻击 if not os.path.abspath(full_path).startswith(os.path.abspath(self.workspace)): return {"success": False, "error": "Invalid file path."} try: os.makedirs(os.path.dirname(full_path), exist_ok=True) with open(full_path, 'w', encoding='utf-8') as f: f.write(content) return {"success": True, "message": f"File '{filepath}' written successfully."} except Exception as e: return {"success": False, "error": f"Failed to write file: {str(e)}"} def get_tools_description(self) -> str: """返回工具的描述，用于构造LLM的提示词。""" descriptions = [ "execute_python_code(code: str): Executes the provided Python code string in an isolated environment. Returns the stdout, stderr, and return code.", "read_file(filepath: str): Reads the content of a file within the workspace.", "write_file(filepath: str, content: str): Writes content to a file within the workspace, creating directories if needed." ] return "\n".join(descriptions)

设计理由：

1. execute_python_code没有使用危险的eval()或exec()，而是通过subprocess运行临时文件，实现了进程级别的隔离，并增加了超时控制。
2. 所有工具都返回结构化的字典，包含success标志和详细结果或错误信息，这为状态管理和LLM理解结果提供了便利。
3. 文件操作限制在workspace目录下，并通过路径解析防止目录穿越攻击，这是最基本的安全措施。

3.2 设计状态管理：记住每一步

我们的状态管理器需要记录对话历史和工具执行结果。

# state_manager.py from dataclasses import dataclass, field from typing import List, Dict, Any import json import os @dataclass class AgentState: """Agent的状态数据类""" original_task: str conversation_history: List[Dict[str, Any]] = field(default_factory=list) # 记录每轮思考、行动、观察 current_step: int = 0 is_finished: bool = False final_result: Any = None class StateManager: def __init__(self, task: str, persistence_file: str = None): self.state = AgentState(original_task=task) self.persistence_file = persistence_file if persistence_file and os.path.exists(persistence_file): self.load_state() def add_interaction(self, thought: str, action: Dict, observation: Dict): """添加一轮思考-行动-观察到历史记录""" self.state.conversation_history.append({ "step": self.state.current_step, "thought": thought, "action": action, "observation": observation }) self.state.current_step += 1 self._persist() def mark_finished(self, result: Any): """标记任务完成""" self.state.is_finished = True self.state.final_result = result self._persist() def get_current_context(self, max_turns: int = 10) -> str: """获取最近的对话历史，用于构造LLM提示词""" recent_history = self.state.conversation_history[-max_turns:] context_lines = [f"Original Task: {self.state.original_task}"] for entry in recent_history: context_lines.append(f"\nStep {entry['step']}:") context_lines.append(f"Thought: {entry['thought']}") context_lines.append(f"Action: {json.dumps(entry['action'], ensure_ascii=False)}") context_lines.append(f"Observation: {json.dumps(entry['observation'], ensure_ascii=False)}") return "\n".join(context_lines) def _persist(self): """将状态持久化到文件（简易版）""" if self.persistence_file: with open(self.persistence_file, 'w') as f: json.dump(self.state.__dict__, f, indent=2, default=str) def load_state(self): """从文件加载状态""" try: with open(self.persistence_file, 'r') as f: data = json.load(f) self.state = AgentState(**data) except Exception as e: print(f"Failed to load state: {e}")

设计理由：状态管理器不仅存储数据，还负责提供构建LLM上下文的方法 (get_current_context)。持久化功能虽然简单，但为长任务提供了中断恢复的可能性。conversation_history的结构化存储是Agent进行连贯推理的生命线。

3.3 实现Agent Loop：让机器“思考”起来

现在，我们将大脑（LLM）、工具和状态连接起来。这里我们使用OpenAI API（或兼容API）作为LLM，你需要替换your_api_key和base_url。

# agent_loop.py import openai from tools import ToolSystem from state_manager import StateManager import json import sys class CodeHarnessAgent: def __init__(self, api_key: str, base_url: str, model: str = "gpt-4"): openai.api_key = api_key openai.base_url = base_url self.client = openai.OpenAI(api_key=api_key, base_url=base_url) self.model = model self.tool_system = ToolSystem() # 初始化时并不创建StateManager，因为任务可能不同 def run(self, task: str, max_iterations: int = 20): """运行Agent处理单个任务""" state_manager = StateManager(task, persistence_file=f"state_{hash(task)}.json") print(f"Starting task: {task}") for i in range(max_iterations): print(f"\n--- Iteration {i} ---") if state_manager.state.is_finished: print("Task already finished.") break # 1. THINK: 构造提示词，调用LLM prompt = self._construct_prompt(state_manager) llm_response = self._call_llm(prompt) thought, action = self._parse_llm_response(llm_response) # 如果LLM认为任务完成 if action.get("action_type") == "final_answer": final_answer = action.get("answer", "Task completed.") print(f"Agent concludes: {final_answer}") state_manager.mark_finished(final_answer) break # 2. ACT: 调用工具 tool_name = action.get("tool_name") tool_args = action.get("args", {}) if not tool_name or tool_name not in ["execute_python_code", "read_file", "write_file"]: observation = {"error": f"Invalid or unknown tool requested: {tool_name}"} else: tool_method = getattr(self.tool_system, tool_name) observation = tool_method(**tool_args) # 3. OBSERVE & 更新状态 print(f"Action: {tool_name}({tool_args}) -> Success: {observation.get('success')}") state_manager.add_interaction(thought, action, observation) # 简单错误处理：如果工具连续失败，可能陷入死循环，这里可以加入更复杂的逻辑 if not observation.get('success'): print(f"Tool execution failed: {observation}") else: # 循环正常结束（非break），意味着达到最大迭代次数 print(f"Reached max iterations ({max_iterations}). Task may not be complete.") state_manager.mark_finished("Stopped due to max iterations.") return state_manager.state.final_result def _construct_prompt(self, state_manager: StateManager) -> str: """构造给LLM的提示词。这是Agent Core的核心逻辑之一。""" context = state_manager.get_current_context() tools_desc = self.tool_system.get_tools_description() prompt = f"""You are an autonomous coding assistant. Your goal is to complete the following task by writing and executing Python code. # TASK {state_manager.state.original_task} # WORKSPACE STATUS You are working in an isolated workspace. You have access to the following tools: {tools_desc} # RECENT HISTORY {context} # INSTRUCTIONS 1. First, THINK about the next step. What needs to be done based on the task and history? 2. Then, decide on an ACTION. You must respond in the following JSON format: {{ "thought": "Your reasoning here...", "action": {{ "action_type": "use_tool" | "final_answer", // If action_type is "use_tool": "tool_name": "execute_python_code" | "read_file" | "write_file", "args": {{ /* arguments for the tool */ }} // If action_type is "final_answer": "answer": "Your final answer to the user." }} }} Important rules: - You can write Python code to solve problems. Use `write_file` to create a `.py` file, then `execute_python_code` to run it. - Always check the results of your actions via `read_file` or the output of `execute_python_code`. - If the task is complete and successful, set `"action_type": "final_answer"` and provide a concise summary. - If you get an error, analyze it and try a different approach in the next step. Now, provide your response as a single JSON object. """ return prompt def _call_llm(self, prompt: str) -> str: """调用LLM API。这里使用OpenAI格式。""" try: response = self.client.chat.completions.create( model=self.model, messages=[{"role": "user", "content": prompt}], temperature=0.1, # 低温度，让输出更确定、更结构化 response_format={"type": "json_object"} # 强制JSON输出 ) return response.choices[0].message.content except Exception as e: print(f"LLM API call failed: {e}") return json.dumps({"thought": "API call failed.", "action": {"action_type": "use_tool", "tool_name": "read_file", "args": {"filepath": "dummy"}}}) def _parse_llm_response(self, response: str) -> (str, dict): """解析LLM的响应，提取thought和action。""" try: data = json.loads(response) thought = data.get("thought", "No thought provided.") action = data.get("action", {}) if not action: action = {"action_type": "final_answer", "answer": "LLM returned no action."} return thought, action except json.JSONDecodeError: print(f"Failed to parse LLM response as JSON: {response[:200]}") return "Failed to parse response.", {"action_type": "final_answer", "answer": "LLM response was invalid JSON."} # 使用示例 if __name__ == "__main__": # 注意：此处需要替换为真实的API信息 agent = CodeHarnessAgent( api_key="your-api-key-here", base_url="https://api.openai.com/v1", # 或你的兼容API端点 model="gpt-4" ) result = agent.run("Write a Python script that calculates the factorial of 10 and prints the result.") print(f"\nFinal Result: {result}")

设计理由与实操心得：

1. 提示词工程是核心：_construct_prompt函数是Agent的“指挥棒”。它清晰地定义了角色、任务、可用工具、历史上下文和最重要的——输出格式。强制JSON输出 (response_format) 大大简化了解析逻辑。提示词中明确的规则（如先写文件再执行）引导LLM按照我们设计的流程工作。
2. 错误处理与鲁棒性：在_call_llm和_parse_llm_response中，我们都加入了基本的异常处理。LLM API可能失败，返回可能不是合法JSON，这些边缘情况必须考虑，否则Agent会崩溃。在实际生产中，这里的错误处理需要更细致，比如重试机制、降级策略等。
3. 温度（Temperature）设置：这里设置为0.1，是为了让LLM的输出更加确定和可预测，这对于需要稳定执行步骤的Agent来说通常比高创造性更重要。
4. 循环终止条件：我们设定了最大迭代次数 (max_iterations) 防止无限循环。更高级的实现还可以根据历史判断是否陷入死循环（例如，连续多次执行相同失败操作）。

运行这个Agent，你会看到它逐步完成“编写并计算10的阶乘”的任务：它可能会先write_file一个factorial.py，然后execute_python_code运行它，再用read_file查看输出，最后给出final_answer。这个过程，就是Harness Agent架构在微观层面的生动体现。

4. 从简易到工业级：Harness Agent 架构的演进与关键挑战

我们上面构建的只是一个教学演示级别的Harness Agent。要将它用于生产环境，解决真实的复杂问题（比如自动化修复一个GitHub Issue，或为一个新项目搭建基础框架），我们还需要跨越诸多工程挑战。这些挑战正是区分玩具与工具的关键。

4.1 工具系统的进阶设计：能力、安全与组合

基础的工具调用只是开始。一个强大的Tool System需要解决更多问题：

• 工具的动态注册与发现：我们的演示中是硬编码三个工具。在实际系统中，工具应该是可插拔的。新的工具（如git_clone,run_tests,query_database）应该能在不修改核心Agent Loop的情况下被注册和发现。这通常通过装饰器或配置文件来实现。
• 工具的组合与编排：有些复杂操作需要按顺序或并行调用多个工具。Harness层可以提供“复合工具”或“工作流”的原语。例如，一个deploy_to_server工具，内部可能依次调用run_tests、build_docker_image、push_to_registry、update_k8s_deployment。
• 更细粒度的安全控制：我们的沙箱还很简陋。生产环境需要：
  • 资源限制：CPU、内存、运行时间的严格配额。
  • 网络隔离：允许访问哪些外部API或内部服务，需要白名单控制。
  • 文件系统沙箱：使用Docker或gVisor等实现强隔离，确保Agent无法逃逸。
  • 基于角色的权限：不同的Agent实例或用户，可访问的工具集和参数范围不同。
• 工具的语义描述与LLM适配：给LLM的工具描述 (get_tools_description) 需要精心设计。描述不仅要准确，还要让LLM容易理解何时使用它。一些框架（如LangChain的Tool Decription）会自动化这部分，但手动优化提示词往往效果更好。

4.2 状态管理的复杂性与持久化策略

随着任务变长、状态变复杂，简单的内存状态和JSON文件存储会捉襟见肘。

• 上下文长度与摘要：LLM有上下文窗口限制。当对话历史很长时，需要智能的摘要策略。不能简单截断最近N条，可能会丢失关键早期信息。需要开发“记忆摘要”功能，将冗长的历史压缩成精炼的要点，在每轮循环中同时提供“详细近史”和“摘要远史”。
• 结构化状态与向量检索：对于代码任务，状态不仅仅是文本对话。它可能包括当前的代码库抽象语法树（AST）、测试结果、依赖关系图等。这些结构化状态如何有效地表示并提供给LLM？一种思路是将关键信息（如函数签名、错误日志）向量化，在需要时通过检索增强生成（RAG）的方式动态注入上下文。
• 分布式与高可用持久化：状态必须持久化到可靠的数据库（如PostgreSQL、Redis），支持多实例Agent的并发访问和状态同步，以实现高可用和水平扩展。

4.3 Agent Loop 的优化：效率、稳定性与可控性

基础的Think-Act-Observe循环可能低效或不稳定。

• 规划与反思（Planning & Reflection）：高级的Agent会在“思考”阶段进行更复杂的规划，不只是想下一步，而是规划一个子目标序列。在“观察”之后，会增加一个“反思”阶段：评估刚才的行动结果是否朝着目标前进，是否需要调整计划。这引入了更复杂的循环结构，如“Plan - Act - Reflect”。
• 并行与分支执行：某些任务可以并行执行（如同时运行多个独立的单元测试）。Agent Loop需要支持产生多个并行的“行动分支”，并等待所有分支完成后再进行下一轮思考。这涉及到更复杂的状态合并与冲突解决。
• 人类审核与干预（Human-in-the-loop）：对于关键操作（如删除生产数据库、合并主分支），Harness必须提供“暂停点”，将行动提交给人类审核，批准后才继续执行。这需要在Loop中引入“等待外部输入”的状态。
• 超时、重试与回滚机制：工具调用可能超时或失败。Harness需要定义重试策略（如指数退避）。对于一系列关联操作，可能需要实现事务语义，在失败时回滚已完成的步骤（例如，如果部署失败，则回滚代码提交）。

4.4 可观测性与调试：给“黑盒”装上仪表盘

当Agent行为不符合预期时，调试它比调试普通程序困难得多，因为涉及LLM的非确定性输出。

• 全链路追踪：必须记录每一个环节的完整信息：输入的提示词、LLM的原始响应、解析后的动作、工具调用的输入输出、消耗的Token数、耗时等。这些数据应存入可查询的日志系统（如ELK Stack）。
• 可视化与回放：一个图形化的界面，能够像播放电影一样回放Agent执行任务的完整步骤，查看每一步的思考、行动和观察，这对于理解和调试复杂任务至关重要。
• 成本监控与优化：每次调用LLM都产生费用。Harness需要监控Token消耗，并可能实现一些优化策略，例如缓存常见的LLM响应、在非关键步骤使用更便宜的模型等。

4.5 与现有开发流程的集成：CI/CD与版本控制

最激动人心的应用场景是将Harness Agent集成到软件开发流水线中。

• 作为CI/CD中的自动审核员：Agent可以自动审查Pull Request中的代码，运行测试，检查代码风格，甚至提出修改建议。Harness需要与GitHub Actions、GitLab CI等工具深度集成，能够克隆代码库、访问CI环境变量等。
• 代码库感知：Agent需要理解项目的整体结构、依赖关系、已有的测试套件。这要求Harness提供“项目上下文加载”工具，能够为LLM构建丰富的代码库索引（可能借助代码嵌入模型）。
• 变更管理与回滚：Agent生成的代码变更，应该以标准的方式（如创建分支、提交、发起PR）集成到版本控制中，而不是直接修改主分支。Harness需要封装这些Git操作，并确保变更可追溯、可回滚。

面对这些挑战，业界已经出现了一些优秀的开源框架，如LangGraph、AutoGen、CrewAI等，它们提供了更高层次的抽象，封装了状态管理、多Agent协作、复杂工作流等能力。理解我们上面从零构建的Harness Agent核心原理，正是为了能更好地理解、评估和高效使用这些高级框架，甚至在其基础上进行定制开发。

5. 避坑指南：构建与使用Harness Agent的常见陷阱

在设计和运行Harness Agent的过程中，我踩过不少坑，也见过很多团队掉进同样的陷阱。这里分享一些最典型的“前车之鉴”，希望能帮你绕开这些弯路。

5.1 提示词设计中的“幻觉”诱导

问题：你给Agent的提示词里写“你可以使用工具A、B、C”，但LLM有时会“幻觉”出一个不存在的工具D，并试图调用它，导致解析失败或执行错误。

根因：LLM是基于概率生成的，即使你列出了工具，它也可能因为训练数据或上下文推理，认为存在其他合理工具。此外，过于复杂的提示词可能导致LLM忽略工具列表部分。

解决方案：

1. 在行动解析层做严格校验：就像我们演示代码中做的，在_parse_llm_response之后，立即检查tool_name是否在已注册的工具白名单中。如果不在，不要尝试调用，而是将“无效工具名”作为观察结果反馈给LLM，让它纠正。
2. 强化提示词中的约束：使用更强烈的措辞，如“You must ONLY use one of the following tools:”，并在每次提示中都重复工具列表。也可以要求LLM在“思考”部分先确认要使用的工具名称。
3. 采用结构化输出框架：使用像Pydantic这样的库，在调用LLM时强制其输出符合预定模式的JSON对象。这比单纯依赖response_format={“type”: “json_object”}更严格，能直接验证工具名等字段的枚举值。

5.2 状态爆炸与上下文管理失控

问题：任务执行了50步后，对话历史变得极其冗长，导致下一次提示词严重超长，要么被截断丢失关键信息，要么API调用因超长而失败且费用激增。

根因：简单地将所有历史记录都塞进上下文，是不可持续的。这不仅是技术限制，也会干扰LLM的注意力，使其难以抓住重点。

解决方案：

1. 实现智能摘要：不要存储原始观察文本。在每一轮“观察”后，用一个单独的、小型的LLM（或规则）对本次行动的结果进行摘要。例如，将“执行了100行测试输出”摘要为“所有单元测试通过”。只将摘要存入长期历史，原始日志存到别处供查询。
2. 分层上下文管理：将上下文分为“工作记忆”（最近3-5步的完整记录）和“长期记忆”（之前所有步骤的摘要）。每次构造提示词时，结合两者。还可以引入“关键记忆”检索，当LLM提到特定概念（如“之前那个文件处理函数”）时，动态从向量数据库中检索相关历史片段注入上下文。
3. 设定明确的迭代上限和状态清理：对于已知的、步骤有限的任务，设定合理的最大步数。对于探索性任务，定期（如每10步）要求LLM自己总结当前进展和剩余目标，并以此为基础重置部分上下文。

5.3 工具执行的安全盲区

问题：你认为已经用Docker做了沙箱，但Agent通过巧妙的组合，依然可能造成破坏。例如，它先write_file一个.sh脚本，再execute_python_code调用os.system去执行这个脚本，从而绕过你对execute_shell工具的直接限制。

根因：安全是一个整体，只防护单个工具点是不够的。需要纵深防御。

解决方案：

1. 最小权限原则：每个工具，甚至每个任务会话，都应在独立的、权限极低的环境中运行。使用像Firecracker这样的微虚拟机，或高度锁定的Docker容器（--read-only根文件系统，无网络，无特权模式）。
2. 输入净化与语义检查：对工具参数进行白名单校验，而非黑名单。例如，对于文件路径，检查是否包含..、是否在允许的目录内。对于要执行的代码，可以用AST解析器做静态分析，禁止导入os、subprocess等危险模块（除非明确允许）。
3. 工具间的副作用监控：建立一个审计日志，记录所有文件系统的修改、网络请求。如果发现一系列工具调用产生了可疑的模式（如创建可执行文件后试图运行它），可以触发警报或中断会话。

5.4 循环停滞与“鬼打墙”

问题：Agent陷入无限循环，反复执行相同的、失败的操作，或者在不同的错误方案间来回切换，无法推进任务。

根因：LLM的“思考”基于当前上下文。如果历史中充满了失败和错误信息，它可能无法跳出错误的思维定式。也可能是因为目标不明确或过于宏大，导致LLM无法找到可行的下一步。

解决方案：

1. 在Harness层实现循环检测：State Manager可以检查最近N步的历史，如果动作和观察的模式高度相似（例如，连续3次尝试用同样的错误语法写文件），则主动干预。干预方式可以是：a) 强行在提示词中加入系统警告；b) 回滚到上一步成功状态；c) 直接终止任务并报错。
2. 任务分解与子目标管理：不要让Agent直接面对一个庞大的任务（如“构建一个博客系统”）。Harness层或上游系统应该先将任务分解为清晰的子任务序列（如“1. 创建项目骨架 2. 实现用户模型 3. 编写文章CRUD API…”），然后让Agent逐个攻克。每完成一个子目标，就提供明确的正反馈，刷新上下文。
3. 引入外部知识或示例：当检测到停滞时，可以从知识库中检索类似任务的成功案例，作为“提示”插入到Agent的上下文中，引导其走向正确的方向。

5.5 对LLM能力的过度期望与低估

问题：期望Agent能完全自主地解决一个模糊、复杂、需要深度领域知识的问题，结果它要么卡住，要么产生荒谬的结果。或者，低估了LLM在清晰指令下的能力，设计了过于繁琐、死板的流程，限制了其创造性和解决问题的能力。

根因：对当前LLM的能力边界认识不清。LLM是强大的模式匹配和推理引擎，但不是全知全能的神。它不擅长需要精确数值计算、长期复杂规划或缺乏训练数据领域的问题。

解决方案：

1. 明确任务边界：在设计Harness和提示词时，就要清楚定义任务的起止范围。对于LLM不擅长的子任务（如复杂计算），通过专用工具（如调用计算引擎、查询数据库）来解决，让LLM专注于它擅长的规划、代码生成和逻辑协调。
2. 设计“逃生舱口”和人工审核点：对于关键决策点或高风险操作，设置必须由人类审核的步骤。不要追求全自动，而是追求“人机协同”的高效。Harness应该让人类介入变得简单自然。
3. 持续评估与迭代：建立Agent性能的评估体系。不仅看最终任务成功与否，还要分析中间步骤的合理性、工具调用的效率、Token消耗等。用这些数据不断迭代优化你的提示词、工具集和Harness流程。记住，构建一个可靠的Agent系统是一个持续的工程迭代过程，而不是一蹴而就的魔法。