1. 引言
在 LLM 应用开发中，Agent 的落地往往比模型本身更复杂。模型负责推理，而 Agent Harness 负责把推理转化为可执行、可观测、可回滚的行动闭环。本课围绕 Agent Harness 的核心概念、关键组件和工程实践展开，帮助你理解为什么需要它，以及如何搭建一个可靠的 Agent 运行框架。
2. 什么是 Agent Harness
Agent Harness 是承载 Agent 运行的一套基础设施，它把模型、工具、记忆、策略和执行环境组织在一起，为 Agent 提供统一的运行上下文和生命周期管理。简单来说，Harness 解决的是「模型怎么调用工具、怎么管理状态、怎么处理错误、怎么结束任务」这些工程问题。
一个典型的 Agent Harness 包含以下核心职责：
- 工具注册与调度：统一管理工具列表，负责参数校验、调用分发和结果回传。
- 状态管理：维护对话历史、任务进度、中间结果等运行时状态。
- 策略编排：决定 Agent 何时调用工具、何时结束、何时需要人工介入。
- 错误处理与重试：捕获工具异常、模型超时等故障，并执行重试或降级策略。
- 可观测性：记录每一步的输入输出、耗时和 token 消耗，便于调试和审计。
3. Harness 的核心组件
下面从工程实现的角度拆解 Agent Harness 的四个关键组件。
3.1 工具层
工具层把外部能力封装成模型可调用的函数。每个工具需要声明名称、描述、参数 schema 和调用逻辑。Harness 负责把模型的工具调用请求解析成真实函数调用，并把结果格式化为模型可读的文本。
python
from pydantic import BaseModel
class SearchTool(BaseModel):
name: str = "web_search"
description: str = "搜索互联网信息"
parameters: dict = {
"query": {"type": "string", "description": "搜索关键词"}
}
def run(self, query: str) -> str:
# 实际调用搜索服务
return f"搜索结果：{query}"</code></pre>
3.2 状态层
状态层维护 Agent 的运行时上下文，包括系统提示词、历史消息、工具调用记录和任务中间变量。状态层需要支持序列化，以便任务中断后可以恢复。
class AgentState:
def __init__(self):
self.messages = []
self.tool_calls = []
self.task_vars = {}
def to_dict(self):
return {
"messages": self.messages,
"tool_calls": self.tool_calls,
"task_vars": self.task_vars,
}</code></pre>
3.3 策略层
策略层决定 Agent 的行为边界。常见策略包括最大迭代次数、工具调用频率限制、置信度阈值和人工审批开关。策略层让 Agent 的行为可预期、可控制。
class AgentPolicy:
def __init__(self, max_steps=10, require_approval=False):
self.max_steps = max_steps
self.require_approval = require_approval
def should_stop(self, step_count):
return step_count >= self.max_steps</code></pre>
3.4 执行层
执行层是 Harness 的主循环，它负责把模型输出解析为动作，并驱动状态更新。一个简化的执行循环如下：
def run_agent(model, tools, policy, initial_state):
state = initial_state
for step in range(policy.max_steps):
response = model.generate(state.messages)
action = parse_action(response)
if action.type == "finish":
return action.result
if action.type == "tool_call":
result = tools[action.name].run(**action.args)
state.messages.append({"role": "tool", "content": result})
raise TimeoutError("超过最大迭代次数")
4. 一个完整的 Harness 示例
下面用一个可运行的 Python 示例串联上述组件，演示一个支持工具调用的最小 Agent Harness。
import json
class SimpleHarness:
def init(self, model, tools, max_steps=5):
self.model = model
self.tools = {t.name: t for t in tools}
self.max_steps = max_steps
def execute(self, user_input):
messages = [{"role": "user", "content": user_input}]
for _ in range(self.max_steps):
reply = self.model.generate(messages)
messages.append({"role": "assistant", "content": reply})
action = self._parse(reply)
if action["type"] == "finish":
return action["output"]
if action["type"] == "tool":
tool = self.tools[action["name"]]
result = tool.run(**action["args"])
messages.append({"role": "tool", "content": result})
def _parse(self, reply):
# 简化解析：假设模型输出 JSON 动作
return json.loads(reply)</code></pre>
这个示例虽然简单，但已经具备 Harness 的核心骨架：主循环、工具分发、状态累积和终止条件。实际生产环境还需要补充超时控制、并发限制、日志埋点和安全审计。
5. 工程实践建议
在真实项目中落地 Agent Harness 时，建议关注以下几点：
工具隔离：工具运行在独立进程或沙箱中，避免模型输出直接操作系统命令。
幂等设计：工具调用尽量设计为幂等，便于失败重试而不产生副作用。
预算控制：对 token 消耗和调用次数设置上限，防止失控成本。
人工审批：高风险操作（如删除数据、发送邮件）应接入人工确认环节。
完整日志：记录每次工具调用的入参、出参、耗时和错误信息，方便复盘。
6. 总结
Agent Harness 是连接模型能力与真实世界的桥梁。它把工具调用、状态管理、策略控制和错误处理统一起来，让 Agent 从「能推理」走向「能可靠地完成任务」。理解 Harness 的分层设计，是构建生产级 LLM 应用的重要一步。