1. 项目概述：一场关于智能体构建范式的思辨

最近在社区里，关于如何构建一个真正高效、可靠的AI智能体（Agent）的讨论又热了起来。一个核心的争论点在于：我们到底应该让代码来设计并驱动整个智能体的“缰绳”（Harness），还是应该让大模型（Model）本身成为这个驱动力的核心？这个问题，乍一看像是技术选型的哲学辩论，但实际上，它直接决定了我们构建的Agent是“提线木偶”还是“自主智能体”，影响着开发效率、系统稳定性和最终能力的上限。

我自己在构建和部署多个生产级AI应用的过程中，对这两种路径都进行过深入的实践。所谓的“Code designs Harness”，指的是开发者通过编写详尽的规则、流程控制逻辑和状态机代码，来构建一个坚固的框架（Harness），大模型在这个框架内更像是一个被调用的、功能强大的“子程序”。而“Model drives Harnesses”则是一种更激进的思路，它试图让大模型自身理解任务、拆解步骤、调用工具，甚至动态调整执行策略，代码提供的Harness更像是一个轻量级的“运行时环境”或“安全沙箱”。

这两种范式没有绝对的优劣，但它们适用于完全不同的场景和阶段。新手可能会觉得让模型驱动一切很酷，仿佛实现了真正的AGI；而老手则深知，在复杂的业务逻辑和严苛的稳定性要求面前，一个由精心设计的代码所构筑的Harness是何等重要。接下来，我就结合自己的踩坑经验，为大家深度拆解这两种范式的内核、适用场景以及如何在实际项目中做出明智的选择。

2. 核心理念拆解：代码驱动与模型驱动的本质区别

要理解这场辩论，我们首先得抛开那些华丽的术语，回到最根本的问题：在一个AI智能体系统中，“控制权”和“决策流”究竟掌握在谁手里？

2.1 代码设计缰绳：确定性框架下的模型工具化

在这种范式下，Harness是一个由开发者完全掌控的、确定性的执行引擎。它的核心思想是“不相信模型有规划能力，只相信它有执行特定子任务的能力”。

1.1.1 核心特征

• 流程固化：整个Agent的工作流是预先用代码定义好的。例如，一个客服Agent的流程可能是：1. 意图识别 -> 2. 槽位填充 -> 3. 知识库查询 -> 4. 回复生成。每一步都是一个固定的模块。
• 模型角色单一：大模型在这里通常只承担某一环节的任务，比如只在“回复生成”环节被调用，或者分别被用于“意图识别”和“回复生成”。它不负责思考“下一步该做什么”。
• 强边界与强验证：Harness代码会严格定义模型的输入输出格式，并对模型的输出进行解析和验证。如果模型返回了非预期格式的内容，代码会进行重试、降级或报错。
• 状态外置：整个对话或任务的状态（如用户已提供的信息、当前步骤等）完全由外部代码（数据库、内存对象）来维护，模型对此无感知。

1.1.2 优势与适用场景

• 优势：
  • 高可控性与可预测性：系统行为完全符合设计预期，易于调试和测试。
  • 高稳定性：单一环节的模型调用失败，可以通过规则降级（如返回兜底话术）来保证核心流程不中断。
  • 易于集成：可以很方便地将Agent嵌入到现有的、复杂的软件系统中，因为它的接口和行为是固定的。
  • 成本可控：精确控制模型调用的时机和内容，避免无意义的、耗资巨大的长上下文或复杂思考链。
• 适用场景：
  • 垂直领域任务：流程明确、规则清晰的场景，如订单查询、数据提取、固定格式报告生成。
  • 对稳定性要求极高的生产环境：例如金融、医疗领域的辅助工具，容错率极低。
  • 将大模型作为传统软件的一个增强组件来使用。

实操心得：在做一个内部数据分析助手时，我们采用了这种范式。Harness代码会先解析用户的自然语言问题，将其转换成标准的SQL查询语句模板，然后调用大模型仅仅用于将模板中的中文条件变量替换成具体的数据库字段名和值。这样做，既利用了模型的理解能力，又绝对保证了最终生成的SQL语法100%正确，避免了模型“胡编乱造”一个SQL语句导致查询失败甚至数据安全风险。

2.2 模型驱动缰绳：将规划与决策权赋予模型

这种范式是当前AI Agent研究的前沿方向，其核心是相信大模型具备任务分解、工具调用和自主规划的能力。Harness在这里退化为一个提供工具集、环境交互和安全约束的“平台”。

1.2.1 核心特征

• 动态规划：Agent接收到目标后（如“帮我制定一份本周市场分析报告”），由大模型自身来规划步骤：先搜索最新行业动态，再整理内部销售数据，接着进行竞品分析，最后生成报告。
• 自主工具调用：Harness向模型暴露一套工具（Tools）的API描述（如search_web(query),query_database(sql),generate_chart(data)）。模型根据当前规划，自主决定调用哪个工具、传入什么参数。
• 循环与反思：模型驱动范式通常包含一个“感知-思考-行动”的循环。模型会观察上一步行动的结果，评估是否达成目标，并决定下一步行动。高级的Agent（如ReAct模式）还会进行“反思”，从错误中学习。
• 状态内化：任务进度、历史观察等信息，通常以提示词（Prompt）或上下文（Context）的形式传递给模型，由模型在内部维持一种“状态感”。

1.2.2 优势与挑战

• 优势：
  • 极强的灵活性与泛化能力：对于未预先编程的新任务，只要在模型能力范围内，就有可能通过自主规划完成。
  • 更接近“智能”：能够处理开放域、多步骤的复杂任务，表现出一定的推理和决策能力。
  • 开发范式更简洁：开发者无需为每一个可能的工作流编写代码，只需定义好工具集和初始目标。
• 挑战与风险：
  • 不可预测性：模型的规划可能出错、陷入死循环或调用不恰当的工具。
  • 高昂的成本与延迟：自主规划意味着多次模型调用和长上下文，成本是代码驱动范式的数倍甚至数十倍。
  • 验证与调试困难：当一个复杂任务失败时，很难定位是规划错误、工具调用错误还是模型生成错误。
  • 安全与合规风险：模型可能自主调用敏感工具或生成不合适的内容。

踩坑记录：我们曾尝试用模型驱动范式做一个自动竞品调研Agent。结果发现，模型时常会陷入“反复搜索同一关键词”的循环，或者在规划步骤时遗漏关键的数据分析环节，直接开始写结论。更棘手的是，它的失败没有规律，每次的“死法”都不同，使得系统性修复变得异常困难。这让我们深刻认识到，在现阶段，完全放任模型驱动，需要极强大的监控、评估和熔断机制作为“安全带”。

3. 架构设计与技术选型深度解析

理解了核心理念，我们来看看在具体架构时，两种范式分别对应怎样的技术栈和设计模式。这里没有银弹，只有权衡。

3.1 代码驱动Harness的典型架构

这种架构很像传统的微服务或工作流引擎，核心是“Orchestration”（编排）。

2.1.1 分层架构一个稳健的代码驱动Harness通常包含以下层次：

1. 接口层：接收用户输入（API调用、消息等），进行初步的清洗和标准化。
2. 流程编排层（核心）：这是Harness的大脑，通常是一个状态机或一个直接的过程调用链。它决定当前处于哪个阶段，并调用相应的处理器。
   • 技术选型参考：对于简单线性流程，直接用代码顺序调用即可。对于复杂状态流，可以考虑使用轻量级的状态机库（如Python的transitions），或者直接使用工作流引擎如Apache Airflow（偏重批处理）或Temporal/Cadence（擅长长周期、可靠的工作流）。在AI时代，LangChain或Semantic Kernel的“Chain”概念，本质上也是一种由代码编排的、确定性的执行图。
3. 处理器/工具层：包含各种功能模块。其中一部分是“模型处理器”，专门负责格式化Prompt、调用大模型API、解析输出。另一部分是纯逻辑工具，如数据库查询、计算、API调用等。
4. 状态管理与上下文层：负责存储和管理整个会话的状态。可以使用内存字典（单机）、Redis（分布式）或数据库。关键是要设计好状态的结构，使其能清晰反映流程进度。
5. 输出与渲染层：将最终的处理结果组装成对用户友好的格式（文本、富文本、数据、文件等）。

2.1.2 关键技术组件

• Prompt模板引擎：如Jinja2。将流程、状态、用户输入变量化地注入到预设的Prompt模板中，是控制模型行为的关键。
• 输出解析器：这是保证稳定性的生命线。必须对模型的返回进行强制结构化解析。
  • LangChain的PydanticOutputParser是绝佳选择，它要求模型返回符合预定JSON Schema的内容，并自动进行校验和重试。
  • 也可以使用正则表达式或自定义的解析函数，但健壮性较差。
• 熔断与降级机制：当模型调用超时、返回格式错误或内容质量过低时，必须有预案。
  • 重试：对瞬时错误进行有限次重试。
  • 降级：切换到更小、更快的模型（如从GPT-4降到GPT-3.5），或切换到基于规则的回复。
  • 熔断：连续失败达到阈值后，暂时屏蔽对故障模型的调用。

# 一个简化的代码驱动Harness核心片段示例 class CustomerServiceHarness: def __init__(self, llm_client, state_store): self.llm = llm_client self.state = state_store async def process_message(self, session_id, user_input): # 1. 获取或初始化当前会话状态 current_state = self.state.get(session_id) or {"step": "intent_detection"} # 2. 基于状态的路由与编排 if current_state["step"] == "intent_detection": # 调用意图识别处理器 intent = await self._detect_intent(user_input) current_state["intent"] = intent current_state["step"] = "slot_filling" self.state.save(session_id, current_state) return await self._ask_for_slot(intent) elif current_state["step"] == "slot_filling": # 填充槽位，并判断是否填满 filled = await self._fill_slot(current_state, user_input) if filled: current_state["step"] = "query_and_response" self.state.save(session_id, current_state) # 状态变更，递归调用进入下一阶段 return await self.process_message(session_id, "") else: return await self._ask_for_next_slot(current_state) # ... 其他步骤

3.2 模型驱动Harness的典型架构

这种架构的核心是“Foundation Model + Tools”，框架代码主要负责工具调用循环和上下文管理。

2.2.1 核心循环：ReAct模式目前最主流的模型驱动范式是ReAct (Reasoning + Acting)。其架构核心是一个循环：

1. Thought：模型分析当前情况（目标、历史、可用工具），思考下一步该做什么。
2. Action：模型决定调用一个工具，并生成格式化的调用请求（如ToolName[{"arg1": "value"}]）。
3. Observation：Harness执行工具调用，并将结果（或错误信息）作为观察返回给模型。
4. 重复1-3步，直到模型认为任务完成，输出最终答案。

2.2.2 关键技术组件与框架

• Agent执行引擎：负责运行ReAct循环。你需要自己实现这个循环控制器，或者使用成熟框架：
  • LangChain Agent：提供了多种Agent类型（如Zero-shot ReAct, Structured Chat），内置了工具调用解析和循环逻辑，是快速上手的选择。
  • AutoGen：由微软推出，支持多智能体协作，智能体之间可以通过对话来完成任务，架构更复杂但也更强大。
  • LangGraph：LangChain的新组件，允许你用图的方式显式地定义智能体的工作流，比传统的Agent循环更可控，是介于“完全代码编排”和“完全模型驱动”之间的一个优秀折中方案。
• 工具描述与调用：如何让模型理解工具是关键。
  • 函数描述：使用详细的自然语言描述工具的功能、输入参数和输出。OpenAI的Function Calling和现在的Tools Calling就是为此设计的。
  • 结构化描述：使用JSON Schema或Pydantic模型来定义工具，框架可以自动将其转换为模型能理解的描述。
• 长上下文管理：随着循环进行，历史记录（Thought, Action, Observation）会越来越长。必须有效管理上下文，防止超出模型令牌限制。
  • 策略：摘要压缩（让模型自己总结历史）、滑动窗口（只保留最近N轮）、选择性记忆（只保留重要的Observation）。

# 一个基于LangChain的简易模型驱动Agent示例 from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain_community.llms import OpenAI from langchain.prompts import PromptTemplate # 1. 定义工具 def search_web(query: str) -> str: # 模拟网络搜索 return f"关于'{query}'的搜索结果摘要..." web_tool = Tool(name="WebSearch", func=search_web, description="用于搜索互联网最新信息") # 2. 准备模型和Prompt llm = OpenAI(temperature=0) prompt = PromptTemplate.from_template( """你是一个有帮助的助手。你可以使用以下工具： {tools} 请遵循以下格式： 问题：用户的问题 思考：你需要思考做什么 行动：要调用的工具名，输入应为工具参数 观察：工具返回的结果 ...（思考/行动/观察可以重复多次） 最终答案：根据观察得出的最终答案 开始！ 问题：{input} 思考：{agent_scratchpad}""" ) # 3. 创建Agent和执行器 agent = create_react_agent(llm, tools=[web_tool], prompt=prompt) agent_executor = AgentExecutor(agent=agent, tools=[web_tool], verbose=True) # 4. 执行 result = agent_executor.invoke({"input": "特斯拉最新的电池技术有什么突破？"}) print(result["output"])

4. 实战场景下的范式选择与混合策略

理论说再多，不如看实战。我以三个常见的场景为例，分析如何选择和设计Harness。

4.1 场景一：企业内部知识库问答机器人

• 需求：员工通过自然语言提问，获取公司内部文档、手册、政策中的准确信息。要求回答精准、可溯源、绝对不允许捏造信息。
• 分析：这是一个典型的**检索增强生成（RAG）**场景。流程高度确定：1. 问题理解与关键词提取 -> 2. 向量检索/全文检索 -> 3. 相关文档片段召回 -> 4. 基于片段合成答案 -> 5. 引用溯源。
• 范式选择：代码驱动Harness为主。
  • 为什么？流程固定，核心难点在于检索的准确性和答案的忠实性，而非任务规划。让模型去“规划”如何检索，反而会引入不确定性和“幻觉”风险。
  • 设计要点：
    1. Harness代码严格管控流程。检索部分可以使用BM25+向量检索混合策略，代码来决定权重和召回数量。
    2. 大模型仅用于最后一步的“答案合成”。Prompt需要强约束，如“严格仅根据提供的上下文回答问题，如果上下文没有足够信息，请直接说‘根据现有资料无法回答’”。
    3. 必须实现引用溯源，Harness代码需要将模型生成的答案与它所依据的文档片段ID对应起来，这是模型自身难以可靠完成的。

4.2 场景二：自动化数据分析与报告生成Agent

• 需求：用户用自然语言描述一个分析需求（如“对比一下Q3和Q4各产品线的营收和增长率，找出增长最快的三个”），Agent能自动查询数据库、进行数据处理、生成图表和文字结论。
• 分析：这是一个多步骤、有条件分支的复杂任务。用户的需求可能非常开放，涉及数据查询、计算、排序、可视化等多个环节。
• 范式选择：混合策略（代码定义主干，模型驱动分支）。
  • 为什么？完全代码驱动，需要预判所有可能的分析需求，工作量巨大且不灵活。完全模型驱动，SQL生成错误、计算逻辑错误的风险太高。
  • 设计要点：
    1. 代码定义高层工作流：Harness代码规定基本阶段：需求澄清 -> 数据探查与查询 -> 分析计算 -> 可视化与报告。这是一个确定性的主干。
    2. 模型驱动具体实现：
       • 需求澄清阶段：可以用模型与用户多轮对话，明确指标、维度、过滤条件。
       • SQL生成阶段：这是关键且高风险环节。可以采用“模型生成 + 代码验证/修正”的混合模式。模型生成初步SQL，Harness代码连接一个测试数据库或使用SQL解析器进行语法验证和轻量级逻辑检查（如是否查询了不存在的字段）。如果出错，将错误信息反馈给模型让其修正。这比完全依赖模型或完全手写SQL效率都高。
    3. 计算与可视化阶段：可以再次用代码驱动，调用固定的Pandas计算库和Matplotlib/Plotly图表库，因为具体的计算逻辑（如增长率公式）是确定的。

4.3 场景三：自主研究型智能体

• 需求：给定一个开放主题（如“评估固态电池在电动汽车领域的商业化前景”），Agent能自动搜索最新资料、阅读分析、整理不同观点、最终生成一份结构化的研究报告。
• 分析：这是最开放、最复杂的场景。任务步骤无法预先确定，需要根据搜索到的信息动态调整研究方向和深度。
• 范式选择：模型驱动Harness为主，但需加固“护栏”。
  • 为什么？任务的非结构化程度极高，必须依赖模型的规划、筛选和综合能力。
  • 设计要点：
    1. 提供强大的工具集：Harness需要集成多种工具：通用网页搜索、学术数据库搜索、PDF文档解析、内容摘要等。
    2. 设计精密的提示词工程：初始Prompt需要明确角色（“你是一位资深行业分析师”）、目标、报告格式要求，并嵌入规划范例。
    3. 设置严格的“护栏”：
       • 循环次数限制：防止无限搜索循环，最多执行N个“思考-行动”循环。
       • 关键节点人工审核：可以在生成报告大纲后、或最终报告生成前，设置一个“暂停点”，将中间结果提供给用户确认。
       • 事实核查工具：对于关键数据或结论，可以设计一个工具，让其从多个信源进行交叉验证。
    4. 使用更高级的框架：此类任务适合使用LangGraph或AutoGen。LangGraph允许你定义一些关键的检查节点（如“研究范围是否过大？”），用代码逻辑来干预模型的自主流程，实现更精细的控制。

5. 性能、成本与可靠性工程实践

无论选择哪种范式，当Agent走向生产环境时，性能、成本和可靠性是必须跨越的三座大山。

5.1 性能优化：降低延迟，提升吞吐

• 代码驱动范式的优化：
  • 异步与非阻塞：确保Harness的IO操作（网络调用、数据库查询、模型API调用）全部使用异步，避免阻塞整个流程。Python的asyncio是基础。
  • 并行与缓存：对于独立的子任务（如同时查询多个数据源），使用asyncio.gather进行并行处理。对频繁使用的、不变的数据（如知识库索引、工具定义）进行内存缓存。
  • 模型调用批处理：如果多个会话在同一阶段需要调用模型，可以考虑将请求批量化发送给支持批处理的API，能显著降低平均延迟。
• 模型驱动范式的优化：
  • 思维链（CoT）压缩：在ReAct循环中，模型的“思考”过程可能很长。可以训练一个轻量级模型或使用提示词技巧，让Agent学会输出更简洁的“思考”，减少无用令牌。
  • 工具调用的优化：工具的执行时间可能很长（如爬取一个网页）。考虑让工具调用本身也是异步的，或者设置超时，避免Agent长时间等待一个工具。
  • 使用更快/更小的模型进行规划：实验表明，对于任务规划（Thought），可能不需要GPT-4级别的能力，使用GPT-3.5 Turbo或Claude Haiku这类更快更便宜的模型，就能取得不错的效果，而只在最终生成答案时使用最强模型。

5.2 成本控制：精打细算每一分钱

大模型API调用是主要成本来源，尤其是长上下文和多次调用。

• 上下文长度管理：这是成本控制的命脉。建立上下文窗口的“滑动窗口”或“摘要”机制，坚决丢弃过期信息。对于代码驱动范式，精心设计每个步骤的Prompt，只注入必要上下文。
• 模型分级调用：建立模型梯队。简单的分类、提取任务用便宜的小模型；复杂的推理、创作任务再用昂贵的大模型。Harness代码需要根据任务类型路由到不同模型。
• 避免无意义的“思考”：在模型驱动范式中，监控Agent的思考过程。如果发现它在一个简单问题上陷入冗长的、重复的思考，应主动中断并降级处理。
• 预算与熔断：为每个用户或每个任务设置API调用预算和令牌预算。超出预算立即停止，并返回友好提示。

5.3 可靠性保障：构建自愈的智能体系统

生产环境的Agent必须健壮。

• 全面的错误处理：
  • 模型API错误：网络超时、速率限制、服务不可用。必须有重试机制（带退避策略）和备选模型。
  • 工具执行错误：工具调用失败、返回异常数据。Harness需要捕获这些错误，并将其转化为模型能理解的“观察”信息，让模型有机会调整行动。
  • 输出解析错误：模型返回了无法解析的内容。应触发重试（使用更严格的Prompt），或降级到安全回复。
• 可观测性与监控：
  • 全链路日志：记录每一个步骤的输入、输出、耗时、模型使用情况、令牌消耗。这是调试的基石。
  • 关键指标监控：成功率、平均响应时间、平均令牌消耗、工具调用失败率、模型调用失败率。设置警报。
  • 溯源与审计：对于模型驱动的Agent，必须完整记录每一次“思考-行动-观察”的循环，以便在出现问题时复盘决策过程。
• 验证与评估：
  • 单元测试：为每个工具函数、每个流程处理器编写单元测试。
  • 集成测试：构建涵盖主要用户场景的测试用例集，定期运行，确保核心流程畅通。
  • 基于LLM的评估：对于开放域任务，可以引入另一个LLM作为“裁判”，对Agent的最终输出进行质量评估（相关性、准确性、有用性），实现自动化的质量监控。

6. 未来展望与个人实践心得

这场“Code vs Model”的辩论，短期内不会有胜负。它反映的是AI工程化进程中，控制与自由、确定性与创造性之间的永恒张力。我的判断是，未来的主流范式不会是二选一，而是一种深度嵌套的混合体。

我们可以预见的是，代码（Harness）会越来越“智能”，它可能内嵌一些学习能力，能根据历史数据自动优化流程路由或Prompt模板。同时，模型（尤其是Agent模型）会越来越“可靠”，通过更好的训练（如强化学习人类反馈，RLAIF）和架构设计（如思维树ToT，图推理），其规划能力和工具调用的准确性会大幅提升。

从个人实践角度，我的建议是：

1. 从代码驱动开始：尤其是当你解决的是明确的商业问题时。先用一个稳固的、代码驱动的Harness把核心业务流程跑通，创造价值。这是风险最低、最可控的路径。
2. 在关键环节引入模型驱动：当流程中出现难以用规则覆盖的“模糊地带”时（如上述的需求澄清、SQL生成），尝试用模型驱动的方式去解决这个子问题，同时用代码为其构筑坚实的护栏。
3. 拥抱LangGraph这类新范式：它代表了混合范式的未来。用图来定义流程主干和关键检查点（代码控制），用智能体节点来处理其中需要灵活性的模块（模型驱动）。这提供了前所未有的控制粒度。
4. 保持对底层原理的关注：无论框架如何演变，理解提示词工程、上下文管理、思维链、工具调用这些核心概念，远比熟练使用某个特定框架更重要。这些才是应对未来变化的元能力。

最终，构建AI智能体不是追求最酷的技术，而是寻找在特定约束下解决问题的最优解。这个最优解，往往存在于代码的严谨与模型的灵动之间那片广阔的灰度地带。我们需要做的，就是成为一名熟练的架构师，在这两者之间找到那个精妙的平衡点。