1. 从“能跑”到“跑得稳”：Agent 稳定性问题的工程化破局思路
做过 Agent 项目的人大概都有过这种体验：Demo 阶段一切丝滑，一旦放到真实业务里跑上几天，各种幺蛾子就冒出来了。同一个用户问题，今天回答得头头是道，明天可能就胡言乱语；昨天还能正确调用工具，今天突然开始瞎编参数；更别提多轮对话里上下文越滚越长，模型开始“失忆”或者“串台”。这些问题单独看都是小毛病，但凑在一起，就足以让一个看起来不错的 Agent 产品在真实场景里彻底失去用户信任。
我前后参与过几个 Agent 相关的项目落地，从最早的“提示词调优靠玄学”，到后来慢慢摸索出一套相对系统的工程化方法，踩过的坑可以说能写满一个笔记本。这个过程中我越来越强烈地意识到一件事：Agent 的稳定性问题，本质上不是模型能力问题，而是工程问题。模型本身的能力边界确实存在，但大量所谓的“不稳定”，其实来源于我们构建 Agent 的方式——提示词结构松散、工具调用缺乏校验、状态管理混乱、异常处理缺失、缺乏可观测性。这些问题，都可以通过工程化的手段来系统性地解决。
“Harness Engineering”这个词，是我在和一些同行交流时逐渐形成的一个概念。Harness 原意是“马具”或“安全带”，引申为对强大但不可控的事物进行约束和引导的装置。放到 Agent 语境里，Harness Engineering 指的是围绕 Agent 构建一整套工程化的约束、校验、监控和恢复机制，让 Agent 在真实业务场景中能够稳定、可预期地运行。它不是简单地写几句“请你务必准确”的提示词，而是从架构层面、流程层面、代码层面去系统性地提升 Agent 的可靠性。
这篇文章适合所有正在做或准备做 Agent 落地的开发者、产品经理和技术负责人。无论你用的是哪种模型、哪种框架，只要你的 Agent 需要面对真实用户、处理真实任务，这里面的思路和方法都能直接参考。我会从整体设计思路讲起，然后拆解核心细节和实操要点，接着给出完整的实操流程和关键实现，最后分享一些常见问题的排查技巧。整篇内容基于我在实际项目中的经验总结，涉及具体参数和代码的地方会给出可直接参考的方案。
2. 整体设计思路：为什么 Agent 需要“马具”
2.1 先搞清楚 Agent 不稳定的根源在哪里
在动手解决稳定性问题之前，得先把问题的来源理清楚。我观察下来，Agent 的不稳定表现虽然五花八门，但根源基本可以归到以下几类：
第一类是输入的不确定性。用户输入千奇百怪，同一个意图可能有几十种表达方式，还夹杂着错别字、口语、省略、指代。Agent 如果对输入的处理不够鲁棒，后续所有环节都会跟着出问题。
第二类是模型输出的随机性。即使输入完全相同，大语言模型的输出也可能不同。这种随机性在创意场景是优点，但在需要精确执行的任务场景就是灾难。温度参数调低能缓解，但不能根治。
第三类是工具调用的脆弱性。Agent 调用外部工具时，参数格式错误、工具返回异常、超时、限流，任何一个环节出问题都可能导致整个任务失败。而且模型往往不会正确处理这些异常，它会“假装”工具调用成功了，然后基于错误的前提继续往下走。
第四类是状态管理的混乱。多轮对话中，上下文不断累积，关键信息被淹没，模型开始遗忘或混淆。如果涉及多步骤任务，中间状态的保存和恢复更是容易出问题。
第五类是缺乏可观测性。出了问题不知道哪里出的，只能靠猜。没有日志、没有追踪、没有指标，优化就无从谈起。
这五类问题，对应的正是 Harness Engineering 要解决的五个方向：输入规范化、输出约束、工具调用加固、状态管理、可观测性建设。
2.2 Harness Engineering 的核心设计原则
基于上面的问题分析，我总结出几条核心设计原则，后面所有的具体方案都是围绕这些原则展开的。
原则一：不要信任模型的任何输出，除非经过校验。这是最重要的一条。模型输出的所有内容，在进入下一个环节之前，都必须经过程序化的校验。格式对不对、参数全不全、值在不在合理范围内，这些都要用代码去检查，而不是靠模型“自觉”。
原则二：每个环节都要有明确的成功/失败判定。一个步骤执行完，必须能明确知道它是成功了还是失败了。不能有“大概成功了”这种模糊状态。判定标准要具体、可程序化。
原则三：失败要能恢复，不能一崩到底。任何环节失败后，要有重试、降级、回滚的机制。重试几次、怎么重试、降级到什么程度，这些都要提前设计好。
原则四：所有关键路径都要可观测。每一步的输入、输出、耗时、结果状态，都要记录下来。出了问题能快速定位，优化的时候有数据支撑。
原则五：约束要分层，不能一刀切。不同场景对稳定性的要求不同，约束的强度也应该不同。比如闲聊场景可以宽松一些，涉及资金操作就必须极度严格。分层设计能让系统在稳定性和灵活性之间取得平衡。
2.3 整体架构分层
按照上面的原则，我把 Agent 的 Harness 架构分成四层，从外到内依次是：
接入层负责输入规范化。用户输入进来后，先做清洗、意图识别、参数提取，把非结构化的自然语言转成相对结构化的请求。这一层的关键是尽可能把不确定性挡在外面。
编排层负责流程控制。根据请求类型，决定走什么流程、调用哪些工具、按什么顺序执行。这一层要处理分支、循环、并行、超时、重试等逻辑。关键是要让流程可预期、可控制。
执行层负责具体的模型调用和工具调用。这一层要处理输出校验、格式转换、异常捕获。关键是每个执行单元都要有明确的契约。
观测层贯穿所有层，负责日志、追踪、指标、告警。关键是让系统的运行状态透明化。
这四层不是必须严格对应的代码模块，而是一种逻辑划分。实际实现时可以根据项目规模灵活调整，但每一层的职责要清晰。
3. 核心细节解析与实操要点
3.1 输入规范化：把不确定性挡在门外
输入规范化是 Harness 的第一道防线。很多稳定性问题，如果在输入环节就处理好，后面根本不会发生。
具体怎么做？我的经验是分三步走。
第一步是清洗。去掉多余的空白、特殊字符、控制字符，统一标点符号。这一步看起来简单，但能避免很多莫名其妙的解析错误。比如用户从某些编辑器复制过来的文本可能带有零宽字符，这些字符肉眼看不见，但会让字符串匹配失败。
第二步是意图识别。判断用户这次输入到底想干什么。可以用一个轻量级的分类模型，也可以用规则匹配，或者直接用大模型做分类。关键是意图类别要定义清楚，且互斥。我见过一些项目意图定义得模棱两可，导致后续流程频繁走错分支。
第三步是参数提取。从输入中提取出执行任务所需的关键参数。这一步要特别注意缺失参数的处理。如果关键参数缺失，应该主动追问，而不是让模型去猜。让模型猜的结果就是它开始编造，这是很多稳定性问题的源头。
这里有个实操心得：参数提取的结果一定要做类型和范围校验。比如提取到日期，要检查是不是合法日期；提取到金额，要检查是不是正数、有没有超出限额。这些校验用代码做，不要交给模型。
注意：输入规范化不要过度设计。我见过有的项目在输入环节做了十几层处理，结果正常请求也被搞得面目全非。规范化的目标是“把明显有问题的输入挡掉”，而不是“把所有输入都改造成理想形态”。
3.2 输出约束：让模型在笼子里跳舞
模型输出的随机性是 Agent 不稳定的核心来源之一。输出约束的目标，就是把模型的输出限制在一个可预期的范围内。
最直接的手段是结构化输出。让模型按照指定的 JSON Schema 输出，然后用代码校验。现在很多模型 API 都支持强制 JSON 输出，这个功能一定要用上。但要注意，即使 API 支持，也要在代码里再做一次校验，因为模型偶尔还是会输出不符合 Schema 的内容。
Schema 的设计有几个要点。字段要少而精，不要试图在一个输出里塞太多信息。类型要明确，字符串就是字符串，数字就是数字，不要用字符串表示数字。枚举值要穷举，能用枚举的地方就用枚举，减少模型自由发挥的空间。必填和选填要分清，必填字段缺失就直接判定失败。
除了格式约束，还有内容约束。比如限制输出长度、限制特定词汇、限制数值范围。这些约束可以通过提示词实现，但更可靠的方式是在代码里做后处理。提示词约束是“软约束”，代码校验是“硬约束”，两者结合效果最好。
还有一个容易被忽视的点是输出的一致性校验。同一个请求多次执行，输出应该基本一致。如果差异过大，说明这个环节的稳定性不够，需要加强约束。可以定期做一致性测试，把差异率作为一项指标来监控。
3.3 工具调用加固：别让模型“假装”成功
工具调用是 Agent 最容易出问题的环节。模型生成工具调用参数，参数可能格式错误；工具执行可能超时、报错、返回异常数据；模型可能误解工具返回结果。每一个环节都需要加固。
参数校验是第一道关。模型生成的参数，在真正调用工具之前，必须经过严格的校验。类型对不对、必填项全不全、值在不在允许范围内，这些都要检查。校验不通过，不要直接调用工具，而是把错误信息返回给模型，让它重新生成。这里要设置重试次数上限，避免无限循环。
调用超时和重试是第二道关。任何外部调用都必须设置超时。超时时间根据工具的正常响应时间来定，一般设置为正常时间的 2 到 3 倍。超时后要有重试机制，但重试要区分情况：网络超时可以重试，参数错误重试也没用。重试次数一般 2 到 3 次，每次重试可以加一点退避时间。
返回结果校验是第三道关。工具返回的数据，不能直接丢给模型，要先校验。返回格式对不对、关键字段有没有、数据是否合理，这些都要检查。如果工具返回异常，要明确告诉模型“工具执行失败了”，而不是让模型去猜。我见过太多案例，工具明明报错了，模型却基于错误的前提继续往下编，最后输出一个看起来合理但完全错误的结果。
幂等性设计是第四道关。对于有副作用的操作（比如写数据、发消息、扣款），必须保证幂等。同一个请求重复执行，结果应该一致。实现方式可以是唯一请求 ID、去重表、状态机等。这一条在涉及资金或重要数据的场景是必须的。
提示：工具调用的日志要记录完整的请求参数和返回结果。出问题的时候，这些日志是排查的第一手资料。但要注意脱敏，敏感信息不能明文记录。
3.4 状态管理：让 Agent 有“记忆”但不“混乱”
多轮对话和长流程任务中，状态管理是稳定性的关键。状态管理做不好，Agent 就会“失忆”或者“串台”。
我的经验是把状态分成三类分别管理。
会话状态是跟用户对话相关的短期状态，比如当前话题、已确认的信息、待办事项。这类状态生命周期短，但更新频繁。建议用一个结构化的对象来维护，每次对话后更新，而不是把所有历史消息都塞进上下文。
任务状态是长流程任务中的中间状态，比如当前执行到哪一步、已经完成了哪些子任务、下一步要做什么。这类状态需要持久化，因为任务可能跨会话、跨天。建议用数据库或键值存储来保存，每个任务一个记录。
全局状态是跨会话的长期状态，比如用户偏好、历史行为。这类状态更新频率低，但影响面广。建议单独存储，使用时按需加载，不要一股脑塞进上下文。
状态管理的核心原则是上下文里只放当前需要的信息。很多项目为了“保险”，把所有历史都塞进上下文，结果上下文越来越长，模型注意力被分散，关键信息反而被淹没。正确的做法是：上下文里只放当前步骤必需的信息，其他信息通过状态查询按需获取。
还有一个技巧是状态变更要记录版本。每次状态更新，记录变更前后的值和变更原因。这样出问题的时候可以回溯，看看是哪一步把状态改坏了。
3.5 可观测性建设：让问题无处遁形
可观测性是 Harness Engineering 的基础设施。没有可观测性，前面所有的加固都是盲人摸象。
可观测性包括三个支柱：日志、指标、追踪。
日志要记录关键路径上的每一个决策点和执行结果。日志的粒度要适中，太粗了没用，太细了噪音大。我的经验是：每个工具调用、每次模型调用、每个状态变更、每个异常，都要有日志。日志要结构化，方便后续查询和分析。
指标要覆盖几个关键维度：成功率、延迟、重试次数、异常率。成功率按环节统计，能快速定位哪个环节最脆弱。延迟按分位数统计，P50、P95、P99 都要看，平均值会掩盖问题。重试次数能反映系统的“隐性不稳定”。异常率按类型统计，能发现高频问题。
追踪要能还原一个请求的完整执行路径。每个请求分配一个唯一 ID，所有相关日志都带上这个 ID。这样出问题的时候，可以通过 ID 把整个执行链路串起来看。追踪的粒度要到每个步骤的输入输出。
注意：可观测性建设要避免两个极端。一个是记录太少，出了问题什么都查不到；另一个是记录太多，存储成本高且噪音大。建议先覆盖关键路径，然后根据实际排查需求逐步细化。
4. 实操过程与核心环节实现
4.1 环境准备与基础框架搭建
动手之前，先把基础环境搭好。我用的是 Python 生态，核心依赖包括：一个大模型调用库（比如 OpenAI 官方 SDK 或兼容接口）、一个 Web 框架（FastAPI 就够用）、一个数据库（PostgreSQL 或 SQLite 都行）、一个日志库（structlog 或标准 logging 加 JSON formatter）。
项目结构建议这样组织：
agent_harness/ ├── config/ │ └── settings.py # 配置管理 ├── core/ │ ├── input_normalizer.py # 输入规范化 │ ├── output_validator.py # 输出校验 │ ├── tool_guard.py # 工具调用加固 │ ├── state_manager.py # 状态管理 │ └── observability.py # 可观测性 ├── agents/ │ └── base_agent.py # Agent 基类 ├── tools/ │ └── registry.py # 工具注册 └── main.py # 入口这个结构不是必须的，但分层清晰，便于后续扩展。核心思路是把 Harness 的各个能力做成独立的模块，Agent 在运行时按需调用。
配置管理用 Pydantic 的 BaseSettings，把模型名称、API 地址、超时时间、重试次数这些参数都放到配置文件或环境变量里。不要硬编码在代码里，否则换环境的时候很麻烦。
4.2 输入规范化模块的实现
输入规范化模块的核心是一个normalize函数，接收原始输入，返回结构化请求。实现上分三步：
import re from pydantic import BaseModel, Field, validator class NormalizedRequest(BaseModel): intent: str = Field(..., description="意图类别") params: dict = Field(default_factory=dict, description="提取的参数") raw_input: str = Field(..., description="原始输入") missing_params: list = Field(default_factory=list, description="缺失的必填参数") def clean_text(text: str) -> str: # 去除零宽字符和控制字符 text = re.sub(r'[\u200b-\u200f\u2028-\u202f]', '', text) # 统一空白 text = re.sub(r'\s+', ' ', text).strip() return text def normalize(raw_input: str, intent_schema: dict) -> NormalizedRequest: cleaned = clean_text(raw_input) # 意图识别（这里用规则示例，实际可以用模型） intent = classify_intent(cleaned) # 参数提取 params = extract_params(cleaned, intent_schema.get(intent, {})) # 检查缺失参数 required = intent_schema.get(intent, {}).get("required", []) missing = [p for p in required if p not in params] return NormalizedRequest( intent=intent, params=params, raw_input=cleaned, missing_params=missing )这里的关键是intent_schema的定义。每个意图对应一个 Schema，说明需要哪些参数、参数类型是什么、是否必填。这个 Schema 是输入规范化的依据，也是后续校验的标准。
参数提取可以用正则、可以用模型、也可以混合。我的经验是：能用规则的地方用规则，规则覆盖不了的用模型。规则稳定、快、可解释；模型灵活但不可控。混合使用效果最好。
4.3 输出校验模块的实现
输出校验模块的核心是validate函数，接收模型输出和期望的 Schema，返回校验结果。
from pydantic import BaseModel, ValidationError import json def validate_output(raw_output: str, schema: type[BaseModel]) -> tuple[bool, any, str]: try: # 尝试解析 JSON data = json.loads(raw_output) except json.JSONDecodeError as e: return False, None, f"JSON 解析失败: {e}" try: # 用 Pydantic 校验 validated = schema(**data) return True, validated, "" except ValidationError as e: return False, None, f"Schema 校验失败: {e}"这个函数返回三个值：是否通过、校验后的对象、错误信息。调用方根据返回值决定下一步：通过就继续，不通过就把错误信息返回给模型让它重新生成。
重试逻辑要单独封装：
def call_with_validation(prompt: str, schema: type[BaseModel], max_retries: int = 3): for attempt in range(max_retries): raw = call_model(prompt) ok, result, error = validate_output(raw, schema) if ok: return result # 把错误信息拼回提示词，让模型修正 prompt = f"{prompt}\n\n上次输出有误：{error}\n请修正后重新输出。" raise RuntimeError(f"重试 {max_retries} 次后仍未通过校验")这里有个细节：重试时要把错误信息反馈给模型。直接重试同样的提示词，模型很可能犯同样的错误。把错误信息拼进去，模型才有机会修正。
4.4 工具调用加固的实现
工具调用加固的核心是一个装饰器，包裹所有工具函数，自动处理校验、超时、重试、日志。
import functools import time from typing import Callable def guarded_tool(max_retries: int = 3, timeout: float = 10.0): def decorator(func: Callable): @functools.wraps(func) def wrapper(*args, **kwargs): last_error = None for attempt in range(max_retries): try: start = time.time() result = func(*args, **kwargs) elapsed = time.time() - start log_tool_call(func.__name__, args, kwargs, result, elapsed, "success") return result except TimeoutError as e: last_error = e log_tool_call(func.__name__, args, kwargs, None, 0, "timeout") time.sleep(0.5 * (attempt + 1)) # 退避 except Exception as e: last_error = e log_tool_call(func.__name__, args, kwargs, None, 0, f"error: {e}") # 参数错误不重试 if isinstance(e, (ValueError, TypeError)): break time.sleep(0.5 * (attempt + 1)) raise ToolExecutionError(f"工具 {func.__name__} 执行失败: {last_error}") return wrapper return decorator用的时候直接装饰工具函数：
@guarded_tool(max_retries=3, timeout=10.0) def query_database(sql: str) -> dict: # 实际查询逻辑 ...这个装饰器做了几件事：记录每次调用的日志、超时后重试、参数错误不重试、重试时退避。这些逻辑如果每个工具都写一遍，既冗余又容易漏。用装饰器统一处理，既简洁又可靠。
4.5 状态管理的实现
状态管理我用一个StateManager类来封装，提供 get、set、snapshot 三个核心方法。
import json import sqlite3 from datetime import datetime class StateManager: def __init__(self, db_path: str): self.conn = sqlite3.connect(db_path) self._init_table() def _init_table(self): self.conn.execute(""" CREATE TABLE IF NOT EXISTS states ( task_id TEXT PRIMARY KEY, state TEXT NOT NULL, version INTEGER DEFAULT 1, updated_at TEXT NOT NULL ) """) self.conn.commit() def get(self, task_id: str) -> dict: row = self.conn.execute( "SELECT state FROM states WHERE task_id = ?", (task_id,) ).fetchone() return json.loads(row[0]) if row else {} def set(self, task_id: str, state: dict): current = self.get(task_id) version = current.get("_version", 0) + 1 state["_version"] = version state["_updated_at"] = datetime.now().isoformat() self.conn.execute(""" INSERT INTO states (task_id, state, version, updated_at) VALUES (?, ?, ?, ?) ON CONFLICT(task_id) DO UPDATE SET state = excluded.state, version = excluded.version, updated_at = excluded.updated_at """, (task_id, json.dumps(state), version, state["_updated_at"])) self.conn.commit() def snapshot(self, task_id: str) -> dict: return self.get(task_id)这个实现有几个要点。版本号用于检测并发冲突，如果两个请求同时更新同一个任务，版本号能帮助发现问题。更新时间用于排查问题，看看状态是什么时候变的。快照用于调试，出问题的时候可以看看当时的状态是什么。
状态更新的时候，我建议只更新变化的字段，而不是整个覆盖。这样可以避免并发更新时互相覆盖。实现上可以先 get 再 merge 再 set，但要注意加锁。
4.6 可观测性的实现
可观测性我用 structlog 加自定义的追踪 ID 来实现。
import structlog import uuid from contextvars import ContextVar trace_id_var = ContextVar("trace_id", default=None) structlog.configure( processors=[ structlog.processors.add_log_level, structlog.processors.TimeStamper(fmt="iso"), structlog.processors.JSONRenderer() ] ) logger = structlog.get_logger() def new_trace(): trace_id = str(uuid.uuid4()) trace_id_var.set(trace_id) return trace_id def log_event(event: str, **kwargs): logger.info(event, trace_id=trace_id_var.get(), **kwargs)每个请求进来先调new_trace()生成追踪 ID，后续所有日志都自动带上这个 ID。查询日志的时候按 trace_id 过滤，就能还原整个执行链路。
关键路径上要埋点。比如输入规范化完成后记录一次，模型调用前后各记录一次，工具调用前后各记录一次，状态变更记录一次。这些日志看起来多，但出问题的时候就是救命稻草。
指标方面，我建议至少统计这几个：请求总数、成功率、平均延迟、P95 延迟、重试率、异常率。这些指标按小时或按天聚合，画成趋势图，能直观看到系统健康度的变化。
5. 常见问题与排查技巧实录
5.1 模型输出格式不稳定怎么办
这是最常见的问题。明明提示词里写了要输出 JSON，模型还是时不时输出一段自然语言加 JSON 的混合体。
排查思路：先看是不是提示词不够明确。提示词里要明确说“只输出 JSON，不要有任何其他内容”，并且给出具体的 Schema 示例。如果还不行，看看是不是模型本身对 JSON 输出的支持不好，换一个对结构化输出支持更好的模型。
解决技巧：用 API 层面的强制 JSON 输出功能。现在主流模型 API 都支持response_format参数，设置成{"type": "json_object"}就能强制 JSON 输出。但要注意，即使这样，也要在代码里做校验，因为模型偶尔还是会输出不符合 Schema 的内容。
还有一个技巧是在提示词里给出完整的 Schema 定义和示例。不要只说“输出 JSON”，而是给出具体的字段名、类型、示例值。模型看到具体示例，输出会稳定很多。
5.2 工具调用参数错误频繁发生
模型生成的工具调用参数经常格式不对，比如该传数字传了字符串，该传数组传了单个值。
排查思路：先看工具的参数定义是不是清晰。参数名要语义明确，参数类型要在描述里写清楚。如果参数定义模糊，模型就容易猜错。
解决技巧：在工具描述里给出参数示例。比如user_id: str, 例如 "u_12345"。示例比描述更直观，模型看了示例就不容易搞错类型。另外，参数校验失败时，把具体的错误信息返回给模型，比如“user_id 应该是字符串，你传的是数字”，模型看到具体错误更容易修正。
5.3 多轮对话中上下文越来越长
对话轮次多了之后，上下文越来越长，模型开始遗忘早期信息，或者把不同轮次的信息混淆。
排查思路：看看是不是把所有历史消息都塞进了上下文。如果是，这就是根因。上下文长度是有限的，塞得越多，每个信息分到的注意力越少。
解决技巧：只保留最近 N 轮对话，更早的信息摘要后保留。摘要可以用模型生成，也可以用规则提取关键信息。另外，把关键信息（比如用户 ID、订单号、已确认的参数）单独存到状态里，每次对话时按需注入，而不是依赖上下文记忆。
5.4 工具调用超时导致任务卡死
外部工具响应慢或者挂掉，导致整个任务卡死。
排查思路：看看有没有设置超时。如果没有，这是首要问题。如果有，看看超时时间是不是太长，或者超时后有没有正确处理。
解决技巧：所有外部调用必须设置超时，超时时间根据工具的正常响应时间来定。超时后要有降级方案，比如返回缓存数据、跳过该步骤、或者明确告诉用户“该功能暂时不可用”。不要让任务无限等待。
5.5 问题排查速查表
| 问题现象 | 可能原因 | 排查方向 | 解决技巧 |
|---|---|---|---|
| 输出格式不稳定 | 提示词不明确、模型不支持 | 检查提示词、检查 API 参数 | 强制 JSON 输出、给出 Schema 示例 |
| 工具参数错误 | 参数定义模糊、缺少示例 | 检查工具描述 | 补充参数示例、错误信息反馈 |
| 上下文遗忘 | 历史消息全塞入上下文 | 检查上下文长度 | 只保留最近 N 轮、关键信息单独存 |
| 任务卡死 | 未设超时、超时未处理 | 检查超时配置 | 设置超时、降级方案 |
| 状态混乱 | 状态更新无版本、并发冲突 | 检查状态管理 | 加版本号、只更新变化字段 |
| 问题难定位 | 日志缺失、无追踪 ID | 检查日志覆盖 | 加追踪 ID、关键路径埋点 |
5.6 几个踩过的坑
坑一：过度依赖提示词约束。早期我总想着用提示词解决所有问题，写了一大堆“请你务必”“你一定要”。后来发现，提示词约束是软约束，模型该犯错还是犯。真正可靠的是代码校验，提示词只是辅助。
坑二：重试逻辑写得太简单。一开始重试就是简单循环，失败了就重来。后来发现，有些错误重试有用（比如网络抖动），有些错误重试没用（比如参数错误）。重试要区分错误类型，还要加退避，否则会给下游造成压力。
坑三：日志记录太随意。早期日志就是 print，出问题的时候根本查不到。后来改成结构化日志，加上追踪 ID，排查效率提升了一个数量级。这个投入非常值得。
坑四：状态管理想得太简单。一开始觉得状态就是存个字典，后来发现并发更新、版本冲突、状态回滚都是问题。状态管理需要认真设计，不能随便糊弄。
坑五：忽视降级方案。总想着“一切正常”的情况，没考虑“出问题了怎么办”。后来发现，降级方案才是稳定性的最后一道防线。宁可功能少一点，也不能整个系统崩掉。
6. 一些个人体会和后续扩展方向
Harness Engineering 这套方法，我在几个项目里实践下来，效果是明显的。最直观的变化是：Agent 的异常率从最初的百分之十几降到了百分之二以内，用户投诉大幅减少，排查问题的时间从半天缩短到几分钟。当然，这套方法也不是银弹，它解决的是工程层面的稳定性问题，模型本身的能力边界还是存在的。但至少，它能让 Agent 在模型能力范围内，稳定地发挥出应有的水平。
后续还可以从几个方向继续深化。一是自动化测试，把常见的输入输出组合做成测试用例，每次改动后自动跑一遍，防止回归。二是灰度发布，新版本先在小流量上跑，观察指标正常后再全量。三是自适应约束，根据历史表现动态调整约束强度，表现好的环节放松约束，表现差的环节加强约束。四是多 Agent 协作的稳定性，当多个 Agent 协同工作时，通信协议、任务分配、结果汇总都需要额外的稳定性保障。
这些方向我还在探索中，有新的心得再和大家分享。如果你也在做 Agent 落地，欢迎交流踩坑经验。
