Harness Engineering：给AI Agent套上可控缰绳的工程实践

1. Harness Engineering到底是什么：先厘清这个被反复提及的概念

最近在折腾AI Agent应用落地的时候，我发现一个特别有意思的现象：不少团队已经能轻松调通大模型接口，也能用各种框架把Agent跑起来，但真正把系统推到生产环境时，总会遇到同一类问题——Agent“太野了”。

它会在没人盯着的时候连续调十几次外部接口，会把敏感数据拼进Prompt，会在某个工具返回异常时陷入死循环，甚至会编造一个不存在的执行结果给你看。这时候大家才开始意识到，光有模型能力和工具调用还不够，Agent系统真正缺的是一个“缰绳”。这个给Agent套上缰绳、把它控制在一个可控边界里的工程化实践，就是标题里说的Harness Engineering。

Harness这个词本来就是“马具、缰绳、安全背带”的意思，放到AI Agent工程里，指的是一整套围绕Agent运行时的约束、观测、调度和治理机制。它不等于某个具体框架，也不是某种算法，而是一种工程范式：把Agent当作一个需要被驾驭的执行体，围绕它搭建控制层，让你既能发挥大模型的自主推理能力，又不会让它跑偏、失控或者烧光你的预算。

我在实际做项目时的一个体会是：模型决定Agent的上限，Harness决定Agent的下限。模型再强，没有缰绳，系统在真实场景里就是不可用的。这篇内容我按“概念—架构—实操—排坑”的顺序，把我自己搭过的Agent系统完整拆一遍，尽量把各个环节讲透，让没接触过Harness Engineering的同学也能照着走一遍，有基础的同学可以直接跳到实操部分。

这个内容适合谁看？如果你正在做AI Agent相关项目，不管是客服机器人、代码助手、数据分析Agent还是自动化流程编排，这篇文章都值得你花二十分钟读完。如果你只是对大模型应用感兴趣，也能从这篇文章里理解一个关键问题：为什么ChatGPT看起来什么都能干，但落到具体业务系统里，却需要一大堆额外的工程代码去约束它。

2. 为什么Agent系统需要一层“缰绳”：失控场景与工程化困境

要理解Harness Engineering的价值，最直观的方式就是先看没有它的时候，Agent系统在真实业务里是怎么翻车的。

2.1 大模型的本质是一台概率生成机

先说一个容易被忽略的基础认知。大模型本质上是一个超大规模的“概率预测器”，它每一步生成的都是基于前文上下文中“最可能的下一个token”，而不是像传统程序那样按照确定逻辑执行。这就意味着同一个Prompt，同一个输入，模型有可能给出完全不同的行为序列。在纯对话场景下这种随机性没问题，但在Agent场景下，随机性会直接变成不可控性。

比如你让Agent去“查询昨天销售数据并生成日报”，它可能先调数据库接口，再调文件服务，然后调消息推送，也可能只调了一次数据库接口就开始编报告。没有Harness层去约束它的行为轨迹，你根本不知道它下一步会干什么。这在工程上是一个根本性的范式转变：以前的软件系统是确定性优先，Agent系统则是“概率性驱动+确定性约束”，而这个确定性约束就必须由外部的工程机制来提供。

2.2 没有约束的Agent：五个高频翻车场景

我把自己项目中踩过的坑和同行聊到的案例整理了一下，至少有以下五种高频翻车场景：

这些场景还有一个共同的麻烦：大模型的复用导致错误很难稳定复现，测试环境跑得好好的，生产环境说崩就崩。传统软件测试那套方法论在Agent系统里会失效，这也倒逼出一套新的工程范式：用代码在Agent执行路径上加护栏。

2.3 从“全自动”到“可控自主”的理念转变

早期做Agent相关的朋友，估计都有过一个想法：我把任务抛给Agent，它自己规划自己执行，多省心。但这个思路在实际项目中很快会被现实毒打。

真实可用的Agent系统，从来不是“完全放养”的。我现在更愿意用“可控自主”来描述Agent生产级应用的范式：Agent在限定范围内自主决策，但每一步都在Harness的监控和约束之内，关键节点需要经过策略校验，异常行为会被及时拦截或者告警。这个思路和自动驾驶的分级逻辑有点像：L4级全自动驾驶很难一步到位，但L2/L3级的辅助驾驶可以在可控范围内大量落地。Harness Engineering就是给Agent装上的“驾驶辅助系统”，让它在你的安全边界内跑得更快。

3. Harness Engineering核心架构：我拆出来的三大控制层面

这个概念提出来之后，很多人会问：那它到底包含哪些部分？是某个模块还是整套系统设计？我根据自己的实践，把Harness拆成三个层面：执行编排层、策略约束层、可观测层。这三个层面各司其职，组合起来就形成了一套完整的Agent治理方案。

3.1 执行编排层：Agent的“行动骨架”

执行编排层是Agent运行的主干，负责定义Agent的基本行动逻辑：它接收到一个任务后，是先规划、再调用工具、再总结结果，还是边执行边调整计划？这个循环逻辑通常被封装成AgentLoop，是整套Harness最核心的运行机制。

一个典型的Agent循环包括以下节点：任务理解、拆解子目标、选择工具、执行调用、评估结果、决定下一步（继续还是终止）。每一个节点都需要在Harness里显式定义，并且留出干预的接口。比如任务理解节点里，Harness可以检查输入是否含敏感信息；工具选择节点里，策略约束层可以校验Agent选择的工具是否符合业务规则。

我在实际项目中，通常会把AgentLoop设计成可配置的模式化结构：用一份JSON配置描述循环策略、最大步数上限、允许调用的工具白名单、终止条件等。这样同一个执行引擎可以灵活适配不同业务场景，不需要为每个场景都重写循环逻辑。

这里重点提醒一句：不要把AgentLoop的逻辑全部交给大模型自己决定。大模型可以负责“选择哪条路”，但“这条路能否走”必须由Harness层用确定性规则来判定。这是整套架构的底线逻辑。

3.2 策略约束层：业务规则的“守门员”

策略约束层是Harness里最硬的控制机制，负责把业务规则、安全边界、权限策略固化成代码逻辑，在Agent执行的关键节点进行拦截或者放行。它有点像微服务架构里的API网关，所有流量都要经过它，只不过这里流过的不是HTTP请求，而是Agent的行动决策。

我常用的策略约束包括几个类型：

• 工具白名单：只允许Agent调用预先注册过的工具，白名单之外的调用直接拒绝。这个策略看似简单，却能在源头阻止绝大多数误操作。
• 参数校验：Agent生成的工具调用参数，在执行前必须进行格式和取值范围校验。比如一个发送短信的工具，接收号码必须匹配手机号正则表达式，内容长度不能超过限制。
• 敏感信息拦截：对Prompt输入和工具返回值做脱敏检测，发现手机号、身份证、密钥等敏感信息时执行掩码或拦截。
• 频控与熔断：对工具调用频率做限制，连续失败达到一定次数时触发熔断逻辑，强制终止本轮Agent运行。
• 人工审批节点：对于高风险的执行动作（如发送外部邮件、删除数据、转账等），Harness在流程中插入“等待人工确认”的节点，只有审批通过后才继续执行后续逻辑。

这层需要特别注意一个设计原则：约束规则必须是确定性代码，不能交给模型判断。模型的判断是概率性的，适合做“语义理解”这类开放性任务；但策略判断是二值性的，放行或拦截必须绝对准确，唯有确定性的规则代码才能做到。

3.3 可观测层：Agent行为的“黑匣子”

可观测性在传统后端系统里已经是标配了，但在Agent系统里，它的重要性被显著放大了。因为Agent的行为路径不可预知，你根本不知道它下一步会调用什么工具、生成什么内容，如果没有完整的日志追踪，出了问题只能干瞪眼。

我建议Harness的可观测层至少覆盖四个维度：

• 轨迹追踪：完整记录Agent每一步的输入输出、思考过程（CoT）、工具调用内容、返回值、耗时和Token消耗。
• 运行指标：统计任务成功率、平均轮数、工具调用分布、异常率等关键指标，用图表展示趋势。
• 审计日志：面向安全合规场景，记录谁在什么时间发起了什么任务、Agent执行了哪些敏感操作、执行结果如何。
• 关联分析：将Agent运行的Trace与业务系统内部的日志、调用链打通，实现全链路追踪。

可观测层的价值不止是事后追责，更重要的是它会帮助你迭代Agent的提示词、工具设计和策略规则。我之前遇到过一个案例：某个Agent场景的成功率长期在65%左右，后来通过查看轨迹日志，发现65%的失败都集中在同一个工具的参数生成环节，修了工具描述后成功率直接拉到了90%以上。没有观测层，这类问题就只能靠猜。

4. 实操：我用Python从零搭了一套极简Harness

理论讲完了，我们来点实际的。下面这套代码是我在一个内部模拟项目里使用的Harness原型，技术栈是Python + FastAPI + 大模型API，核心代码不到三百行，但完整覆盖了执行编排、策略约束和可观测三层能力。如果你正在搭建自己的Agent系统，可以直接照着这个骨架去扩展。

4.1 核心数据模型设计：先定义事件和循环

先定义Agent运行时的核心数据结构。我习惯用一个AgentEvent来统一表达每一步的轨迹事件，后续的日志追踪、指标采集都基于这个模型展开。

python复制# harness_core/models.py
from enum import Enum
from dataclasses import dataclass, field
from typing import Optional, Any, Dict
import time
import uuid

class EventType(str, Enum):
    TASK_START = "task_start"
    PLAN_CREATED = "plan_created"
    TOOL_SELECTED = "tool_selected"
    TOOL_CALL = "tool_call"
    TOOL_RESULT = "tool_result"
    LLM_CALL = "llm_call"
    TASK_END = "task_end"
    ERROR = "error"
    GUARD_VIOLATION = "guard_violation"

@dataclass
class AgentEvent:
    event_type: EventType
    content: Dict[str, Any]
    timestamp: float = field(default_factory=time.time)
    trace_id: str = field(default_factory=lambda: uuid.uuid4().hex)

    def to_dict(self) -> Dict[str, Any]:
        return {
            "trace_id": self.trace_id,
            "event_type": self.event_type.value,
            "timestamp": self.timestamp,
            "content": self.content,
        }

有了事件模型，就可以定义Agent循环的输入输出了。我再加一个AgentContext，用来承载一次完整任务运行中的所有上下文数据，包括用户原始输入、历史消息、工具结果缓存等。

python复制@dataclass
class AgentContext:
    task: str
    history: list = field(default_factory=list)
    tool_results: dict = field(default_factory=dict)
    step_count: int = 0
    trace: list = field(default_factory=list)

    def snapshot(self) -> Dict[str, Any]:
        return {
            "task": self.task,
            "history": self.history[-5:],  # 只保留最近5条，防止上下文膨胀
            "tool_results": self.tool_results,
            "step_count": self.step_count,
        }

这个设计里最值得注意的就是snapshot那行：我只保留最近5条历史消息。上下文膨胀是Agent系统最常见的成本杀手，这个简单的裁剪策略能在不影响任务效果的前提下显著减少Token消耗。

4.2 工具注册与白名单机制

Harness里所有可以被Agent调用的工具，都需要先注册到一个工具注册表里。工具注册表要记录的信息包括工具名称、参数Schema、执行函数、所需权限级别等。这里我用一个装饰器来做工具注册，代码上看很简洁，实际项目里也好维护。

python复制# harness_core/tools.py
import inspect
from typing import Callable, Dict, Any
from pydantic import BaseModel

class ToolRegistry:
    def __init__(self):
        self._tools: Dict[str, dict] = {}

    def register(self, name: str, description: str, params_schema: dict, required_perm: str = "user"):
        def decorator(func: Callable) -> Callable:
            self._tools[name] = {
                "name": name,
                "description": description,
                "parameters": params_schema,
                "func": func,
                "required_perm": required_perm,
            }
            return func
        return decorator

    def available_tools(self, permission_level: str) -> list[dict]:
        tools = []
        for name, meta in self._tools.items():
            if permission_level == "admin" or meta["required_perm"] == permission_level:
                tools.append({
                    "name": name,
                    "description": meta["description"],
                    "parameters": meta["parameters"],
                })
        return tools

    def call(self, name: str, arguments: Dict[str, Any]) -> Any:
        if name not in self._tools:
            raise ToolNotFoundError(f"Tool {name} not registered")
        tool_meta = self._tools[name]
        return tool_meta["func"](**arguments)

这个设计相比直接把工具函数写死在代码里，最大的优势是可审计、可控制。每次Agent调工具都要经过注册表的发现、权限校验和参数校验，想加一个工具只需要注册一下就行，不需要改循环逻辑。权限控制这里我简单分了user和admin两级，实际项目里可以扩展成RBAC那种细粒度权限模型。

4.3 策略约束：GuardRail的实现

接下来是Harness的精华部分：策略约束层，我习惯叫GuardRail。在这个示例里，我实现了一个“工具白名单+敏感操作拦截+执行频控”的守卫链。每个守卫都是一个独立的函数，接收Agent的意图和参数，返回放行或拦截，这样就能灵活组合出不同业务场景所需的策略。

python复制# harness_core/guards.py
from typing import Callable, Dict, Any, List
from dataclasses import dataclass
from .models import AgentEvent, EventType

@dataclass
class GuardResult:
    allowed: bool
    reason: str = ""

Guard = Callable[[str, Dict[str, Any]], GuardResult]

def tool_whitelist_guard(whitelist: set) -> Guard:
    def guard(tool_name: str, args: Dict[str, Any]) -> GuardResult:
        if tool_name in whitelist:
            return GuardResult(allowed=True, reason="tool in whitelist")
        return GuardResult(allowed=False, reason=f"tool {tool_name} not in whitelist")
    return guard

def sensitive_param_guard(sensitive_keys: set) -> Guard:
    def guard(tool_name: str, args: Dict[str, Any]) -> GuardResult:
        for key in sensitive_keys:
            if key in args:
                return GuardResult(allowed=False, reason=f"sensitive param {key} detected")
        return GuardResult(allowed=True, reason="no sensitive param")
    return guard

class GuardRail:
    def __init__(self, guards: List[Guard]):
        self._guards = guards

    def check(self, tool_name: str, args: Dict[str, Any]) -> GuardResult:
        for guard in self._guards:
            result = guard(tool_name, args)
            if not result.allowed:
                return result
        return GuardResult(allowed=True, reason="all guards passed")

有同学可能会问：这些规则不就是普通的代码校验吗，为什么要把它们叫“守卫”而不直接写在工具调用前面？我觉得关键在于这种“守卫链”的设计模式上——它把策略规则从业务逻辑里解耦出来了，你可以像搭积木一样为不同场景组合不同的守卫，而且可以审计每次拦截行为。这比把校验逻辑散落在各个工具函数里要清晰得多。

4.4 主循环编排：把三层串起来

现在把上面几个组件串起来，形成一个完整的Agent主循环。这个循环做的事情是：接收任务，带着上下文调用大模型获取下一步决策，经过GuardRail校验后执行工具调用，记录事件，更新上下文，直到任务完成或触发终止条件。

python复制# harness_core/agent.py
import json
from .models import EventType, AgentEvent, AgentContext
from .tools import ToolRegistry
from .guards import GuardRail, GuardResult

class HarnessAgent:
    def __init__(
        self,
        model_fn,
        tool_registry: ToolRegistry,
        guard_rail: GuardRail,
        max_steps: int = 10,
    ):
        self.model_fn = model_fn
        self.tools = tool_registry
        self.guard = guard_rail
        self.max_steps = max_steps

    def run(self, task: str, permission_level: str = "user") -> dict:
        ctx = AgentContext(task=task)
        ctx.trace.append(AgentEvent(EventType.TASK_START, {"task": task}))

        while ctx.step_count < self.max_steps:
            ctx.step_count += 1
            system_prompt = self._build_system_prompt(permission_level)
            response = self.model_fn(system_prompt, ctx.snapshot())
            action = self._parse_action(response)

            if action["type"] == "finish":
                ctx.trace.append(AgentEvent(EventType.TASK_END, {"result": action["output"]}))
                return self._result(ctx)

            if action["type"] == "tool_call":
                tool_name = action["tool"]
                args = action["args"]
                ctx.trace.append(AgentEvent(EventType.TOOL_SELECTED, {"tool": tool_name}))

                guard_result = self.guard.check(tool_name, args)
                if not guard_result.allowed:
                    ctx.trace.append(AgentEvent(
                        EventType.GUARD_VIOLATION,
                        {"tool": tool_name, "reason": guard_result.reason}
                    ))
                    ctx.history.append({
                        "role": "system",
                        "content": f"Tool call rejected by guard: {guard_result.reason}"
                    })
                    continue

                try:
                    result = self.tools.call(tool_name, args)
                    ctx.trace.append(AgentEvent(
                        EventType.TOOL_RESULT,
                        {"tool": tool_name, "result_summary": str(result)[:200]}
                    ))
                    ctx.tool_results[tool_name] = result
                    ctx.history.append({
                        "role": "assistant",
                        "content": f"调用工具 {tool_name} 得到结果: {str(result)[:500]}"
                    })
                except Exception as e:
                    ctx.trace.append(AgentEvent(EventType.ERROR, {"error": str(e)}))
                    ctx.history.append({
                        "role": "system",
                        "content": f"工具 {tool_name} 执行失败: {str(e)}，请更换方案或修正参数后重试"
                    })

            # 为防死循环，每一步都把当前进度和约束写进模型可见的上下文
            ctx.history.append({
                "role": "system",
                "content": f"当前进度: {ctx.step_count}/{self.max_steps}，请继续或调用finish结束"
            })

        ctx.trace.append(AgentEvent(EventType.ERROR, {"error": "max steps exceeded"}))
        return self._result(ctx)

    def _build_system_prompt(self, permission_level: str) -> str:
        tools_desc = json.dumps(self.tools.available_tools(permission_level), ensure_ascii=False)
        return f"""你是一个被缰绳约束的助手，只能使用以下工具完成用户任务：
{tools_desc}
规则：
1. 不能使用列表之外的工具
2. 如果需要调用工具，输出 JSON：{{"type":"tool_call","tool":"工具名","args":{{...}}}}
3. 任务完成后输出 JSON：{{"type":"finish","output":"最终回答"}}
4. 必须基于工具返回的真实结果回答，严禁编造工具结果。"""

    def _parse_action(self, response: str) -> dict:
        try:
            return json.loads(response)
        except json.JSONDecodeError:
            return {"type": "finish", "output": response}

    def _result(self, ctx: AgentContext) -> dict:
        return {
            "final_output": ctx.history[-1] if ctx.history else "",
            "step_count": ctx.step_count,
            "trace": [e.to_dict() for e in ctx.trace],
        }

这段代码是整个Harness的最小闭环。设计上有几个细节值得说明：

• 工具被拦截后，我不是直接报错终止，而是把拦截原因反馈给模型，让它换一个思路。这一点在实际使用中非常有效，很多任务第一次工具选错了，纠正后能继续正确执行下去。
• 每次调用模型，我都在历史消息里追加当前进度提示。这一步能让模型知道自己已经跑了多少步，显著减少死循环的发生。
• 工具失败的信息同样被放进历史上下文，模型看到具体的报错后会自己调整参数或换方案，这比硬编码的重试逻辑要智能得多。

这套极简Harness跑起来后，一个基本的“数据查询并生成报告”任务完全可以自动走完：Agent拆解任务、选工具、被校验、执行、再生成最终输出，全程有Trace记录。下一步你只需要往注册表里加真实的业务工具，就可以接入生产环境。

5. 上下文工程与Token成本：Harness里最容易被低估的环节

前面我把Harness的架构和核心代码都讲完了，但在真实项目中还有一个环节，它的重要性甚至超过循环和守卫本身——上下文管理。如果上下文管理做得不好，前面的所有设计都会跟着出问题。

5.1 上下文膨胀的连锁反应

大模型的API计费里，输入Token的成本通常是输出Token的3到5倍。这意味着每次你往Prompt里塞的无关内容，都在实打实烧钱。而且上下文太长还会带来另一个隐蔽问题：模型会更难从冗长内容里提取关键信息，也就是俗称的“Lost in the Middle”现象——模型对中间部分的内容关注度和记忆都更弱，对开头和结尾的内容更敏感。

所以上下文管理的第一原则是：只把自己人真正需要的信息放进模型视野。我常用的一个类比是：你的任务是把一个工程师派到现场解决问题，你给他带的报告越多，他翻找关键信息的耗时就越长，开错工具的概率反而越高。给Agent的上下文也同理——精炼、相关、则有条理才能做出更好的决策。

5.2 我常用的四层上下文裁剪策略

在Harness设计里，我一般用四种手段来控制上下文膨胀：裁剪、摘要、筛选、结构化。

裁剪是最简单的手段，就是只保留最近几轮对话和工具结果，代码里的ctx.snapshot()就是这么干的。摘要稍微复杂一点：当历史超过一定长度，我会先用一个小模型把旧的对话压缩成要点，然后替换到上下文里，替代原始长文本。筛选是根据任务需求挑出相关历史，比如当前任务要查数据库，前面的文件操作记录就没必要保留。结构化是把工具返回的长文本转成结构化摘要，比如把数据库返回的100行数据转成“总数100行，其中类型A占60行、类型B占40行”之类的统计描述。

这四层策略可以叠加使用。通常我先做结构化，让每个工具的返回值都尽量短；再做筛选，把不相关的历史丢掉；然后做摘要，把时间跨度大但还有参考价值的内容压缩；最后做裁剪，控制上下文总长度在一个安全的Token预算内。

5.3 Token预算设定实操

我这里给出一个参考配置：如果模型上下文窗口是128K，我通常把Harness层的Token预算设定在30K到50K之间。其中系统提示词控制在2K以内，工具Schema描述控制在5K以内，历史对话控制在10K左右，工具结果缓存控制在15K以内，剩下留给模型输出的空间。

有了预算之后，我会在每次构造Prompt之前先做一次估算，如果超出预算就触发更激进的裁剪策略。这个做法帮我省下过不少钱：在一个每天跑几万次Agent任务的项目里，优化完上下文后单次平均Token消耗从6K降到了2.5K，成本直接降了一半以上，而且任务成功率反而提升了5个百分点——因为模型不再被无关信息干扰了。

6. 常见问题与排查技巧实录：我在Harness迭代中踩过的坑

代码和设计跑通了，不代表一切就万事大吉了。我在几个真实项目里迭代Harness的过程中，积累了一些高频问题和对应的排查思路，整理成一份速查表，希望能帮你少走弯路。

6.1 死循环怎么治

死循环是Agent系统里最让人头疼的问题。现象是Agent不断调用同一个工具或者在同一步和下一步之间反复横跳，每次结果都一样，但模型始终不结束。

我的排查经验是：先把Trace拉出来，看看每次循环时模型收到的上下文到底长什么样。多数情况下你会发现，模型其实“看到”工具结果了，但结果里缺少一个能推进任务的信号。比如一个爬虫工具返回“请求失败”，模型能做的只有重试，如果不给它新的指令，它就重试直到撞上最大步数。

治本的办法有两个：一是把每个工具的返回格式设计得“可决策”——返回值里最好带上“下一步可选动作”的提示；二是在Harness循环里加入“重复检测”逻辑——如果连续N步调用同一个工具且参数相同，就停止这个方向，强制模型切换策略。这个逻辑用代码实现起来很简单，对死循环的抑制效果却很显著。

6.2 GuardRail误伤怎么办

护栏设得太多太严，Agent就动不了了；设得太松，又容易出事。这是做策略约束时最微妙的平衡点。

我的建议是：先设一套比较宽的守卫，跑两周收集真实拦截数据，再根据拦截日志逐步收紧。重点分析那些“拦截但任务成功”和“拦截但任务失败”的案例，前者说明规则可能过严，后者说明规则可能正好拦住了不该放行的行为。每一次规则修改都保存版本，方便回滚对比。

另外，要避免把“业务偏好”写死在GuardRail里。比如某业务规定“查询必须带时间范围”，这属于业务规则，应该放在工具参数校验里，而不是放在Harness通用守卫里。通用守卫只放安全、权限、敏感数据这类跨场景都适用的硬性约束。

6.3 从AgentLoop日志里诊断问题

最后分享一个实操经验：我给每个Harness都单独开了Trace导出功能，把AgentEvent序列化成JSON，可以导入日志分析平台做可视化。事件链路里我觉得最有价值的字段有两个：tool_name和guard_result.reason。

如果某个任务的失败率和某个工具强关联，优先排查这个工具的实现和描述，而不是怀疑模型；如果GuardRail的拦截次数异常上升，优先检查最近改动了哪条业务规则。这种数据驱动的方式帮我快速定位过不少“看起来像玄学”的问题，查到最后几乎都能找到确定性原因——大部分情况下不是模型有问题，而是工程侧的细节没有管理到位。

7. 工具选型参考：自研还是用框架？

关于Harness Engineering的实现方式，还有一个绕不开的选择题：是自研一套，还是基于成熟框架改造？我自己的经验是这样的：如果你的场景是以实验、原型验证为主，框架能帮你快速跑通；如果目标是生产级应用，自研或深度定制几乎是逃不掉的路。

7.1 选择自研的三点考虑

自研Harness的核心优势，是每一层逻辑都掌握在自己手里：工具白名单是可审计的，守卫策略是精准定制的，上下文裁剪规则是可控的，Trace日志自成体系。这套可控性在生产环境是刚需，因为出了问题你要能快速定位、快速修复。

框架的劣势反而在于“顺滑”二字：框架封装得越好，内部的默认逻辑越难改。而且框架版本迭代很快，API变动频繁，一旦你的业务逻辑深度依赖框架的某个实现细节，版本升级就会变成一场灾难。我自己经历过一次框架大版本升级后Agent行为大变样的教训，从那以后就开始推动自研了。

7.2 组合使用：框架做基座，Harness做外壳

如果你的团队确实需要快速起步，也可以用框架承载基础能力（模型调用、工具调用、循环调度），然后在框架外面加一层自己的Harness外壳：写自己的守卫逻辑、自己的上下文管理、自己的Trace出口。这样既享受了框架的便利，又保住了对关键控制点的自主权。

无论走哪条路，我都建议Harness核心代码里不要掺杂具体业务逻辑。Harness只负责控制、约束、观测三个通用能力，具体业务工具注册进来的方式看着像插件系统。做到了这一点，你就能在不同业务场景间复用同一套Harness，这是工程化的真正价值所在。

按照我个人的实践经验，把Harness Engineering想清楚再动手，比先跑通再回头补要有效得多。我最早就是直接把Agent跑起来再补控制层，结果每次加规则都要改循环、动上下文，牵一发动全身，吃了不少苦头。如果你现在刚开始搭建Agent系统，不妨先花几个小时把Harness骨架搭好，再往里面填业务工具和策略规则。这个前置投入会在后续很长一段时间里持续为你省时间，也能让你在Agent工程这条路上走得更稳。