---

核心前提

传统后端开发的终极目标：服务不崩、故障可查、异常可容、结果可靠
Agent工程化（Harness）的终极目标：完全一致
Agent ≠ 脚本调LLM API
Agent = 分布式后端服务（调用LLM/工具/数据库/第三方API，和后端微服务架构一模一样）

---

第一部分：传统后端异常处理 → 生产级Agent鲁棒性思路

后端异常处理不是 try-except 这么简单，是分层捕获、分类处理、容错兜底、可观测的工程体系。

1. 后端异常处理5大核心原则（直接套Agent）

后端原则	对应Agent开发要求	生产级价值
分层捕获（Controller/Service/DAO）	Agent分层：入口层→决策层→工具调用层	精准定位故障，不越级吞异常
异常分类（业务/系统/第三方）	自定义Agent异常：LLM异常/工具调用异常/业务异常	区别处理：重试/熔断/兜底
禁止裸奔（不空catch）	绝不隐藏异常，全量日志+埋点	线上故障可排查
容错兜底（降级/重试/熔断）	LLM挂了→Agent不崩；API超时→自动重试	服务99.9%可用性
标准化响应	统一Agent输出格式	上层系统可对接、可监控

2. Agent异常处理分层设计（完全对标后端）

Agent入口层（用户请求）→ 全局兜底异常（后端全局异常处理器）
  ↓
Agent决策层（意图识别/逻辑编排）→ 业务异常（后端Service层异常）
  ↓
工具调用层（LLM API/搜索/数据库/外部接口）→ 第三方异常（后端DAO/第三方API异常）

3. 后端经典容错方案 → Agent落地实现

1. 重试（瞬时故障）：后端调第三方API超时重试 → Agent调LLM/工具API指数退避重试
2. 熔断（级联故障）：后端断路器 → LLM连续失败，直接熔断，拒绝调用
3. 降级（服务不可用）：后端降级返回默认值 → LLM挂了，Agent返回预设兜底回答
4. 隔离（故障扩散）：后端线程池隔离 → Agent工具调用异步隔离，不阻塞主流程

---

第二部分：传统后端测试 → 生产级Agent测试思路

后端测试不是「测一下正常流程」，是测试金字塔：单元→集成→异常→性能→回归，覆盖100%异常分支（这才是鲁棒的关键）。

1. 后端测试金字塔 → Agent测试落地

测试层级	后端做法	Agent测试做法	核心目的
单元测试	测最小逻辑，Mock所有依赖	测Agent决策/解析逻辑，Mock LLM/工具API	保证核心逻辑无bug
集成测试	测模块+真实依赖	测Agent+真实LLM/工具	保证链路通
异常测试（混沌测试）	刻意制造故障（断网、超时）	模拟LLM限流、超时、500错误	验证容错/兜底/熔断
边界测试	测非法参数	测用户恶意输入、超长文本、无意义请求	防止Agent崩溃
回归测试	自动化用例，迭代必跑	Agent版本更新，自动跑全量用例	不改坏老功能
性能测试	并发压测	多用户并发调用Agent	保证高可用

2. 后端测试核心思想：测试异常比测试正常更重要

生产级服务80%的故障来自异常场景，Agent同理：

• LLM限流报错
• 网络超时
• 工具API返回空值
• 用户输入非法内容

不测试异常的Agent，绝对不能上线。

---

第三部分：生产级Agent 代码模板（异常处理+测试全覆盖）

我用 Python（Agent主流技术栈）写后端标准工程化代码，直接复用构造你的Agent。

依赖安装（后端标准容错+测试库）

# 重试/熔断/日志/测试 全是后端生产级库
pip install tenacity  # 重试（后端标准）
pip install resilient  # 熔断（后端断路器模式）
pip install pytest    # 单元测试（后端标准）
pip install python-dotenv

1. 核心代码：Agent异常处理体系（对标后端微服务）

import logging
import requests
from tenacity import retry, stop_after_attempt, wait_exponential, RetryError
from dataclasses import dataclass

# ======================
# 1. 自定义异常体系（后端标准：分类异常）
# ======================
class AgentBaseException(Exception):
    """Agent根异常"""
    pass

@dataclass
class LLMException(AgentBaseException):
    """LLM调用异常（第三方异常，对标后端第三方API异常）"""
    code: int
    message: str

@dataclass
class ToolCallException(AgentBaseException):
    """工具调用异常（系统异常）"""
    tool_name: str
    error: str

@dataclass
class AgentBusinessException(AgentBaseException):
    """Agent业务异常（业务逻辑异常，对标后端Service异常）"""
    intent: str
    message: str

# ======================
# 2. 后端标准：日志可观测（绝不吞异常）
# ======================
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("ProductionAgent")

# ======================
# 3. 生产级Agent（带重试/熔断/兜底/异常处理）
# ======================
class ProductionAgent:
    def __init__(self, llm_api_key: str):
        self.llm_api_key = llm_api_key
        self.failure_count = 0  # 熔断计数器

    # ----------------------
    # 后端标准：重试机制（指数退避，应对瞬时故障）
    # ----------------------
    @retry(
        stop=stop_after_attempt(3),  # 最多重试3次
        wait=wait_exponential(multiplier=1, min=1, max=5),  # 指数退避
        reraise=True
    )
    def _call_llm(self, prompt: str) -> str:
        """调用LLM API（底层工具调用，对标后端DAO层）"""
        try:
            # 模拟LLM API调用（真实场景替换为OpenAI/通义千问等）
            response = requests.post(
                url="https://api.llm.com/v1/chat",
                headers={"Authorization": f"Bearer {self.llm_api_key}"},
                json={"prompt": prompt},
                timeout=10
            )
            response.raise_for_status()  # 抛出HTTP错误
            return response.json()["answer"]
        
        except requests.exceptions.Timeout:
            raise LLMException(code=408, message="LLM调用超时")
        except requests.exceptions.HTTPError as e:
            raise LLMException(code=response.status_code, message=f"LLM接口报错：{str(e)}")
        except Exception as e:
            raise LLMException(code=500, message=f"LLM未知错误：{str(e)}")

    # ----------------------
    # 后端标准：熔断+降级+兜底（核心鲁棒性）
    # ----------------------
    def _circuit_breaker(self) -> bool:
        """熔断开关：失败>5次，直接熔断"""
        if self.failure_count > 5:
            return True
        return False

    def _fallback_answer(self) -> str:
        """降级兜底回答（后端降级逻辑）"""
        return "我暂时无法处理您的请求，请稍后再试~"

    # ----------------------
    # Agent主入口（对标后端Controller层）
    # ----------------------
    def chat(self, user_input: str) -> dict:
        """
        生产级Agent入口
        返回：标准化响应（后端标准）
        """
        # 1. 熔断判断
        if self._circuit_breaker():
            logger.warning("LLM服务熔断，触发降级")
            return {"code": 200, "data": self._fallback_answer(), "status": "degraded"}

        try:
            # 2. 核心业务逻辑
            if not user_input or len(user_input) > 1000:
                raise AgentBusinessException(intent="invalid_input", message="输入非法：为空或超长")

            # 3. 调用LLM
            answer = self._call_llm(user_input)
            self.failure_count = 0  # 重置熔断计数器

            # 4. 标准化返回（后端统一响应）
            return {
                "code": 200,
                "data": answer,
                "status": "success",
                "trace_id": "trace_123456"  # 链路追踪（后端可观测）
            }

        # ======================
        # 分层异常捕获（后端标准）
        # ======================
        except AgentBusinessException as e:
            logger.error(f"业务异常：{e}")
            return {"code": 400, "error": e.message, "status": "business_error"}

        except RetryError:
            self.failure_count += 1
            logger.error(f"LLM重试3次全部失败，失败次数：{self.failure_count}")
            return {"code": 500, "data": self._fallback_answer(), "status": "llm_failed"}

        except LLMException as e:
            self.failure_count += 1
            logger.error(f"LLM异常：{e}")
            return {"code": e.code, "error": e.message, "status": "llm_error"}

        except Exception as e:
            # 全局兜底捕获（后端全局异常处理器）
            logger.critical(f"Agent未知崩溃：{str(e)}", exc_info=True)
            return {"code": 500, "data": self._fallback_answer(), "status": "system_error"}

2. 测试代码（后端标准测试金字塔，覆盖正常+异常）

新建 test_agent.py，这就是生产级测试思路：

import pytest
from unittest.mock import patch
from agent import ProductionAgent, LLMException, AgentBusinessException

# 初始化Agent
agent = ProductionAgent(llm_api_key="test_key")

# ======================
# 1. 单元测试：Mock依赖（后端标准）
# ======================
@patch.object(ProductionAgent, '_call_llm')
def test_agent_normal_success(mock_llm):
    """测试正常流程"""
    mock_llm.return_value = "你好，我是Agent"
    result = agent.chat("你好")
    assert result["code"] == 200
    assert result["status"] == "success"

# ======================
# 2. 异常测试：核心！（后端生产级必测）
# ======================
def test_agent_invalid_input():
    """测试业务异常：非法输入"""
    result = agent.chat("")  # 空输入
    assert result["code"] == 400
    assert result["status"] == "business_error"

@patch.object(ProductionAgent, '_call_llm')
def test_agent_llm_retry_failed(mock_llm):
    """测试异常：LLM重试全部失败"""
    mock_llm.side_effect = LLMException(code=500, message="LLM挂了")
    result = agent.chat("你好")
    assert result["status"] == "llm_failed"
    assert "暂时无法处理" in result["data"]  # 验证兜底

def test_agent_circuit_breaker():
    """测试异常：熔断触发"""
    agent.failure_count = 6  # 模拟连续失败
    result = agent.chat("你好")
    assert result["status"] == "degraded"

# ======================
# 3. 边界测试（后端标准）
# ======================
def test_agent_long_input():
    """测试边界：超长输入"""
    result = agent.chat("a" * 2000)
    assert result["code"] == 400

3. 运行测试（后端标准命令）

pytest test_agent.py -v

---

第四部分：这就是 Harness Engineering 的本质

你要构造生产级Agent，必须抛弃「调API就行」的思维，完全遵循传统后端软件工程：

1. 异常处理：分层、分类、重试、熔断、兜底、可观测
2. 测试：单元测试Mock依赖、异常测试覆盖所有故障、边界测试防崩溃
3. 标准化：统一响应、日志、链路追踪、可运维

---

=====================================================

补充

深度展开：Agent主流范式 + 后端软件工程对齐 + Harness工程化全维度对比

前置核心定义

Harness Engineering（智能体工程基座）
不是简单加try-catch，是把传统后端服务的：流程编排、状态管理、事务一致性、异常分级、熔断限流、幂等重试、全链路测试、故障自愈整套体系，强行植入AI Agent执行范式中，解决原生LLM范式无约束、无状态、无容错、无流程管控的天生缺陷，最终达到生产级可运维、可监控、可灰度、可故障回滚。

范式本质划分

所有Agent范式只分两大派系：

1. 临场决策派：边思考边执行，无全局顶层规划 → 代表：ReAct、原生Function Call、COT流式推理
2. 预规划执行派：先定全局方案，再分步落地 → 代表：Plan-and-Execute、Tree Plan、Graph Plan
3. 后置修正派：执行完成再自省纠错 → 代表：Reflection/Self-Correct

---

一、全主流Agent范式 原理+流程+原生缺陷+后端工程对标

1. ReAct 范式（Think + Act 交替迭代）

1.1 核心执行逻辑

极简闭环循环：
用户输入 → LLM思考(Thought) → 决策调用工具(Action) → 获取工具观测结果(Observation) → 再次思考 → 再次行动 → 直至输出最终答案
特点：无全局计划表，完全临场迭代，走一步看一步。

1.2 流程伪代码

while 未达成终止条件:
    thought = llm_think(历史对话+观测结果)
    action = 解析思考内容，调用指定工具
    observation = 执行工具拿到返回
    存入上下文记忆

1.3 原生天生缺陷（生产致命坑）

1. 无限迭代死循环：LLM反复思考重复行动，无最大步数约束，资源打爆
2. 局部容错极差：单步工具调用失败 → 整个循环直接断裂，无重试、无跳过
3. 思考不可收敛：容易偏离业务目标，越跑越偏
4. 无状态断点：中断后无法续跑，上下文丢失必须从头重来
5. 无优先级管控：多工具并发调用无序，和后端无接口限流一致

1.4 传统后端技术对标

ReAct = 后端「事件驱动即时业务代码」

• 对标：后端接口里直接串行调用第三方接口，无流程编排
• 优点：轻量、开发快、灵活
• 缺点：无架构约束、异常扩散快、不可管控

1.5 Harness工程化改造（后端思路植入）

1. 循环硬限流：配置最大思考行动轮次（对标后端接口超时时间）
2. 单步隔离异常：每一轮Action单独加重试+超时+异常捕获，单步失败不终止全局循环
3. 步骤幂等标记：给每一次行动加唯一ID，避免重复调用工具（对标后端接口幂等）
4. 快照状态持久化：每轮执行完成落盘上下文，支持中断续跑（对标后端事务快照）
5. 收敛规则注入：硬编码业务终止条件，强制拦截无效思考

1.6 专项测试思路（后端异常测试逻辑）

• 单步工具超时测试、工具返回脏数据测试
• 循环边界测试（达到最大轮次是否正常终止）
• 上下文溢出测试（超长观测结果是否崩溃）

---

2. Plan-and-Execute 先规划后执行范式（工业级最稳主流）

2.1 核心执行逻辑

两段式强拆分，彻底解耦规划层 & 执行层

1. Plan规划阶段：LLM基于用户需求，输出结构化分步执行计划（有序任务列表、依赖关系、所需工具、执行顺序）
2. Execute执行阶段：调度器按照既定计划，逐行严格执行，LLM只负责执行微调，不重新全局改方案
3. 计划全部执行完毕，汇总结果输出

2.2 标准执行链路

1. 用户需求 → 规划大模型生成结构化Plan（数组/JSON流程）
2. 工程层校验Plan合法性（格式、工具是否存在、步骤是否合理）
3. 执行引擎按顺序遍历计划任务
4. 单任务执行失败：重试/跳过/标记异常，不篡改顶层计划
5. 全部任务完成 → 聚合结果回答用户

2.3 原生天生缺陷

1. 计划与现实割裂：LLM制定的理想计划，实际工具环境无法执行（最常见）
2. 静态计划僵化：中途出现新变量，无法动态调整全局方案
3. 步骤依赖卡死：前置任务失败，后置全部阻塞，无降级旁路
4. 规划成本高：复杂需求生成超长计划，耗时、消耗token极高
5. 无计划熔断机制：不合理计划依旧强行执行

2.4 传统后端技术对标

Plan-and-Execute = 后端「分布式工作流引擎 + 定时任务编排」

• 对标：Camunda/Flowable工作流、后端订单分步流程、审批流
• 核心思想：流程预定义，执行强管控，是后端生产系统最成熟架构

2.5 Harness工程化深度改造（后端硬核能力注入）

1. 计划预校验引擎
   后端参数校验思路：强制校验计划格式、工具白名单、步骤数量、逻辑合理性，非法计划直接驳回重生成，禁止无效执行。
2. 步骤分层异常策略
   • 核心必选步骤：失败重试3次+告警
   • 非核心可选步骤：失败直接跳过，走旁路兜底
3. 动态重规划机制
   对标后端流程回滚：连续多步执行失败，触发局部重规划，仅修正异常片段，不推翻全局主流程
4. 计划版本管理
   对标后端代码版本：保存历史执行计划，支持流程回退、灰度切换执行方案
5. 执行资源隔离
   不同计划任务使用独立线程池，避免高优先级流程被阻塞（后端线程池隔离思想）
6. 事务化执行
   支持计划执行半完成回滚，清除无效中间结果

2.6 专项测试体系

1. 计划合法性测试：恶意需求生成畸形计划，校验拦截能力
2. 流程断点测试：中途终止执行，验证续跑能力
3. 依赖故障测试：前置步骤模拟失败，验证后置流程降级逻辑
4. 长流程压测：几十步超长计划，测试调度引擎稳定性

---

3. Reflection 自省纠错范式（后置修正型）

3.1 逻辑

正常执行输出结果 → 自省模型复盘错误、漏洞、信息缺失 → 二次修正重执行 → 输出优化答案
分为：单轮自省、多轮迭代自省

3.2 后端对标

对标后端线上日志审计 + 故障复盘自愈 + 结果二次校验
多用于风控、文案审核、数据校对类Agent

3.3 工程痛点&改造

• 痛点：自省无边界，无限修正
• 改造：限定最大自省轮次、自省触发条件硬编码、自省失败直接沿用原始结果兜底

---

4. Function Call 原生函数调用范式（最底层基础范式）

4.1 逻辑

LLM仅负责解析参数，执行逻辑全部由代码硬编码完成，LLM不参与流程决策

4.2 后端对标

纯后端接口调用，LLM只做参数映射，流程、异常、重试全由工程师手写

4.3 定位

所有高级Agent范式的底层基座，鲁棒性最高，灵活性最低

---

二、四大核心范式 全维度横向对比表（工程视角）

对比维度	ReAct 边想边做	Plan-and-Execute 先规划后执行	Reflection自省修正	原生Function Call
架构模式	事件驱动动态执行	静态流程编排执行	结果后置校验修正	代码硬编码调度
流程可控性	弱（自由发散）	极强（强约束流程）	中等	极强
异常容错原生能力	极差（单步崩全局崩）	良好（分步隔离）	一般（只修正结果）	最优（全自定义）
后端架构对标	零散业务接口	工作流/审批流引擎	事后审核风控	标准RPC接口调用
资源消耗	中等（迭代不可控易超标）	偏高（规划+执行双消耗）	偏高（多轮推理）	最低
业务适配场景	轻量闲聊、简易工具调用	复杂任务、多步骤业务流程、生产落地	文案校对、逻辑纠错、风控审核	高稳定低灵活固定业务
工程改造难度	低（只需加轮次限制）	高（需搭建计划校验+调度引擎）	中	无改造，原生后端逻辑
生产上线鲁棒性	一般（需强约束）	顶级（企业级首选）	良好	顶级
状态管理能力	弱	强（流程状态全留存）	弱	强

---

三、Harness工程化：不同范式统一异常处理体系（后端统一规范）

3.1 三层异常分级（全范式通用，照搬后端）

1. 业务逻辑异常
   需求非法、参数错误、权限不足 → 直接返回标准化业务错误，不重试
2. 执行瞬时异常
   工具超时、网络抖动、LLM限流 → 指数退避重试（tenacity标准方案）
3. 系统级致命异常
   服务宕机、依赖销毁、资源耗尽 → 直接熔断、全局降级、停止调度

3.2 不同范式异常落地差异

1. ReAct 异常落地
   异常粒度：单轮思考行动为最小异常单元
   策略：单轮失败重试，达到最大轮次直接终止循环，输出兜底结果
2. Plan-and-Execute 异常落地
   异常粒度：单步计划任务为最小单元
   策略：
   • 核心任务：重试+告警
   • 次要任务：失败跳过
   • 连续多步失败：触发全局流程降级，执行备用简易计划
3. Reflection 异常落地
   异常粒度：最终输出结果
   策略：自省发现错误重新执行，自省超限直接放行原始结果

3.3 全范式通用生产级约束（Harness核心规则）

1. 所有Agent必须配置硬上限
   ReAct最大迭代轮次、Plan最大计划步数、Reflection最大自省次数（对标后端接口超时）
2. 所有外部调用强制超时
   LLM调用、工具调用统一设置超时时间，杜绝卡死阻塞
3. 全局统一降级兜底
   无论哪种范式彻底失败，必须预设无LLM依赖的静态兜底回答
4. 全链路日志埋点
   规划日志、思考日志、执行日志、异常日志分级打印，对标后端链路追踪TraceID
5. 混沌测试强制注入
   上线前主动注入：超时、500报错、空返回、脏数据，验证所有异常分支

---

四、范式生产级选型策略（企业落地直接用）

1. 快速原型、轻量应用 → 优先 ReAct，加基础轮次+重试约束即可
2. 正式业务流程、多步骤复杂任务、ToB生产系统 → 必选 Plan-and-Execute
   这是目前大厂Agent生产环境唯一主流工程化范式，完美贴合后端流程开发思维
3. 内容审核、文案优化、答案纠错场景 → 搭配 Reflection
4. 超高稳定性、固定流程、金融/政务严谨场景 → 底层 Function Call 手写调度

---

五、进阶延伸：超越传统范式 —— 后端架构升级Agent范式

1. Graph Agent 图流程智能体

对标后端分布式微服务调用拓扑图
把执行步骤做成有向图，支持分支、跳转、条件判断，比线性Plan更灵活，是下一代生产级编排范式。

2. StateFlow Agent 状态流智能体

完全对标后端有限状态机FSM
定义初始化、执行中、异常、暂停、完成五大状态，所有执行严格走状态流转，彻底杜绝LLM自由发散，鲁棒性拉满。

---

最终总结

1. 普通玩具Agent：只套用ReAct/Plan语法，无脑调用LLM API
2. Harness Engineering生产级Agent：
   以后端软件工程思想为骨架，把流程编排、异常分级、重试熔断、状态管理、事务回滚、全链路测试，深度绑定ReAct/Plan-and-Execute等LLM执行范式，约束LLM的不确定性，用工程确定性压制AI随机性；
3. 做可上线Agent优先吃透 Plan-and-Execute，它是后端开发人员最容易上手、最容易做工程化改造、工业落地最成熟的核心范式。

总结

1. Agent工程化 = 后端微服务开发，没有任何区别；
2. 异常处理不是 try-except，是容错体系（重试/熔断/降级）；
3. 测试不是测正常流程，是测所有异常场景（这是鲁棒的核心）；
4. 上面的代码模板直接复用，就是你要的生产级、可上线、不崩的Agent。

这就是行业里说的 Harness Engineering —— 用传统软件工程的严谨性，驾驭AI Agent的不确定性。