智能体模式实战：从ReAct到规划分解，构建可靠AI应用

1. 项目概述与核心价值

最近在探索智能体（Agent）应用开发时，我发现了一个非常有意思的GitHub仓库：keli-wen/agentic-harness-patterns-skill。这个项目名字听起来有点长，但拆解一下就能明白它的核心——“Agentic Harness Patterns Skill”。简单来说，它不是一个完整的应用，而是一个专注于“智能体模式”的“技能库”或“模式集合”。你可以把它理解为一个工具箱，里面装满了用于构建和“驾驭”（Harness）智能体行为的高级设计模式（Patterns）和可复用技能（Skills）。

在当前的AI应用开发浪潮中，直接调用大语言模型（LLM）的API来完成简单任务已经变得非常普遍。然而，当我们试图构建更复杂、更可靠、能处理多步骤工作流的“智能体”时，挑战就来了。如何让智能体记住上下文？如何让它进行有效的工具调用？如何设计它的决策流程，使其在面对复杂问题时能像人类一样分解、规划、执行和反思？这正是“智能体模式”要解决的问题。agentic-harness-patterns-skill这个项目，正是试图将这些前沿的、经过验证的设计模式，封装成易于理解和使用的代码模块，为开发者提供一个高起点的脚手架。

这个项目非常适合以下几类人：一是正在从简单的Prompt工程转向复杂智能体系统开发的工程师；二是希望在自己的应用中引入更强大、更自主AI能力的全栈开发者；三是研究AI应用架构，希望了解业界最佳实践的研究者或技术负责人。通过学习和使用这个项目中的模式，你可以避免重复造轮子，快速构建出具备规划、工具使用、记忆和反思等高级能力的智能体应用。

2. 核心模式深度解析与设计思路

这个项目的核心价值在于其封装的一系列“智能体模式”。这些模式并非凭空想象，而是源于学术界和工业界在构建可靠智能体系统过程中的经验总结。下面，我们来深入拆解几个我认为最关键的核心模式，理解它们背后的设计哲学和解决的问题。

2.1 ReAct（Reasoning + Acting）模式：让思考可见化

ReAct模式可能是当前最著名、应用最广泛的智能体模式之一。它的核心思想是让智能体模仿人类解决问题的方式：先思考（Reason），再行动（Act），并根据行动结果再次思考，形成一个“思考-行动-观察”的循环。

为什么需要ReAct？早期的智能体或简单的提示词工程，往往是让模型直接输出最终答案或执行动作。这在简单问答中有效，但对于需要多步骤推理、工具调用的复杂任务，模型很容易“跑偏”或陷入死循环。ReAct模式通过强制模型在输出最终答案前，先输出其“思考过程”（一段内部推理文本），使得模型的决策逻辑变得透明、可调试。更重要的是，这个“思考”步骤能有效地引导模型去规划下一步该调用哪个工具、传入什么参数。

在agentic-harness-patterns-skill的实现中，ReAct模式通常被抽象为一个状态机或一个循环控制器。它会维护一个任务列表或一个状态上下文，在每一步，模型都会接收当前状态（包括之前的思考、行动和观察结果），然后生成新的“思考”和“行动”。这里的“行动”通常被映射到具体的工具调用，比如调用搜索引擎API、查询数据库、执行一段代码等。

实操心得：实现ReAct时，一个关键细节是如何设计提示词（Prompt）来引导模型输出结构化的“思考”和“行动”。通常我们会使用非常明确的指令，例如：“你是一个助手。为了回答问题，请遵循以下格式：Thought: [你的推理过程] Action: [要执行的动作，格式为工具名: 工具输入]”。在解析模型输出时，需要使用正则表达式或专门的解析器来可靠地提取Thought和Action部分，这是保证循环稳定运行的基础。

2.2 规划与子任务分解模式：化整为零的智慧

当面对一个庞大的、模糊的指令时（例如“为我制定一个为期一周的海南旅游计划，包括预算”），让智能体直接生成完整答案是非常困难的，结果也往往不尽人意。规划与子任务分解模式就是为了解决这个问题。它让智能体首先成为一个“规划者”，将宏大的最终目标拆解成一系列有序的、可执行的子任务。

这个模式的核心组件通常包括一个“规划器”（Planner）和一个“执行器”（Executor）。规划器接收用户指令，并输出一个结构化的任务列表，每个任务都有明确的目标和依赖关系。执行器则按照这个列表，逐个调用相应的技能或工具（可能本身又是一个ReAct智能体）来完成子任务，并汇总结果。

模式优势：

1. 提升任务成功率：分步解决比一步到位更可靠。
2. 增强可控性与可解释性：整个任务流程清晰可见，哪一步出了问题可以快速定位。
3. 便于并行与优化：识别出可以并行执行的独立子任务，提高效率。

在项目的实现中，你可能会看到类似Plan、SubTask这样的数据类（Data Class），以及一个PlannerAgent类。PlannerAgent的提示词会被精心设计，要求其以特定格式（如JSON、Markdown列表）输出规划。这再次体现了“用提示词工程定义智能体行为边界”的思想。

2.3 记忆与反思模式：让智能体拥有“经验”

一个只会机械执行当前指令，而完全忘记之前对话历史和自身行为的智能体，是笨拙且不可靠的。记忆与反思模式旨在为智能体赋予“经验”学习的能力。

• 记忆（Memory）：这不仅仅是保存聊天记录。高级的记忆系统包括：
  • 对话历史记忆：存储完整的用户与智能体交互记录。
  • 实体记忆：专门存储关于特定人物、地点、事件的关键信息，便于快速检索。
  • 向量记忆：将文本信息转换为向量并存入向量数据库（如ChromaDB, Pinecone）。当需要相关信息时，通过语义搜索召回最相关的记忆片段，这是实现“长期记忆”和“知识关联”的关键。
• 反思（Reflection）：这是让智能体变得更“聪明”的进阶能力。在完成一个任务或一系列行动后，智能体可以主动（或被触发）回顾自己的行动轨迹和结果，进行分析和总结。例如：“我刚才为什么失败了？是因为调用的API参数不对吗？”或者“这次成功的策略是什么？可以提炼成经验供下次使用。” 反思的结果可以形成新的记忆存储起来，从而在未来的任务中避免重复错误、复用成功经验。

在agentic-harness-patterns-skill中，记忆模块可能被设计为可插拔的组件，支持多种后端存储。反思则可能作为一个独立的“技能”或“工具”，在任务链的特定节点被调用。

注意事项：记忆不是越多越好。无限制地增长记忆会导致上下文窗口爆炸（增加API成本）和检索效率下降。通常需要设计记忆的摘要、压缩和淘汰机制。例如，当对话轮次过多时，可以将早期对话总结成一段摘要，只保留摘要和近期详细记录。

2.4 工具使用与编排模式：智能体的“手脚”

智能体的强大，很大程度上取决于它所能调用的工具（Tools）。工具可以是任何东西：一个计算器函数、一个网络搜索API、一个代码执行环境，或者一个企业内部系统的接口。工具使用模式的核心是让智能体能够理解工具的描述、根据需求选择合适的工具、并正确构造调用参数。

关键实现点：

1. 工具描述：每个工具都需要一个清晰、结构化的描述，通常包括名称、功能说明、输入参数格式和示例。这个描述会被拼接到模型的系统提示词或上下文里。
2. 工具发现与选择：当智能体需要采取行动时，它需要从庞大的工具库中快速找到最相关的一个或几个。这可以通过在提示词中列举所有工具描述来实现（适用于工具较少时），也可以通过更高级的“工具检索”机制来实现——先将工具描述向量化，根据当前“思考”进行语义搜索召回。
3. 工具编排（Orchestration）：这是指多个工具按照特定逻辑顺序被调用的过程。它可能由上述的“规划”模式驱动，也可能由更复杂的流程控制（如基于图的流程）来管理。工具编排确保了复杂任务中各个步骤的依赖关系和数据流能得到正确处理。

这个项目很可能提供了一套声明式定义工具、并自动将其集成到智能体循环中的框架。开发者只需要用装饰器或配置文件定义好自己的工具函数，框架就能自动处理工具的描述生成、调用解析和结果返回。

3. 项目架构与核心模块实操

理解了核心模式后，我们来看看如何将这些模式落地，即agentic-harness-patterns-skill项目可能的代码架构和关键模块。虽然我们无法看到其未公开的全部代码，但可以根据其命名和模式概念，推断并构建一个合理的、可参考的实现蓝图。

3.1 技能（Skill）的抽象与定义

“Skill”是这个项目名称中的关键词，它代表了可复用的最小能力单元。一个Skill可以非常简单，比如“获取当前时间”；也可以很复杂，比如“分析数据并生成图表”。在架构上，一个Skill通常包含以下几个部分：

1. 描述（Description）：用自然语言清晰说明这个技能是做什么的，这是给大模型“看”的。
2. 输入模式（Input Schema）：定义技能需要哪些参数，以及参数的类型、格式和约束。这通常用JSON Schema或Pydantic模型来定义。
3. 执行函数（Execution Function）：实现技能核心逻辑的代码。可以是同步函数，也可以是异步函数。
4. 输出模式（Output Schema）：定义技能执行结果的格式。

一个典型的Skill定义可能看起来像这样（以Python伪代码为例）：

from pydantic import BaseModel, Field from typing import Optional class WeatherQueryInput(BaseModel): """查询天气的输入参数""" city: str = Field(description="城市名称，例如：北京") date: Optional[str] = Field(default=None, description="查询日期，格式YYYY-MM-DD，默认为今天") class WeatherQueryOutput(BaseModel): """查询天气的输出结果""" city: str date: str weather: str temperature: str humidity: str class WeatherQuerySkill: name = "get_weather" description = "根据城市和日期查询天气情况。" input_schema = WeatherQueryInput output_schema = WeatherQueryOutput async def execute(self, input_data: WeatherQueryInput) -> WeatherQueryOutput: # 这里实现调用真实天气API的逻辑 # 例如：async with aiohttp.ClientSession() as session: ... # 模拟返回 return WeatherQueryOutput( city=input_data.city, date=input_data.date or "2023-10-27", weather="晴", temperature="22°C", humidity="65%" )

项目可能会提供一个基类或装饰器，让开发者可以更方便地定义Skill，并自动完成注册、描述生成等工作。

3.2 智能体运行时（Agent Runtime）与控制流

这是整个系统的“大脑”和“中枢神经系统”。它负责协调模式、管理状态、驱动ReAct循环。一个最小化的运行时可能包含以下组件：

• 状态管理器（State Manager）：维护当前任务执行的状态，包括：原始目标、已完成的步骤列表、当前步骤的输入/输出、积累的记忆等。状态通常是一个字典或特定的状态对象，在整个执行生命周期中流转。
• 提示词组装器（Prompt Assembler）：根据当前状态、可用技能、历史记忆等，动态组装出送给大模型的提示词。这是将业务逻辑转化为模型可理解指令的关键环节。
• 输出解析器（Output Parser）：解析大模型返回的文本，将其结构化，提取出“思考”、“行动”、“最终答案”等部分。需要健壮地处理模型输出可能存在的格式偏差。
• 工具/技能路由器（Tool/Skill Router）：根据解析出的“行动”指令，找到对应的Skill并调用其execute方法。
• 循环控制器（Loop Controller）：实现ReAct等模式的主循环逻辑。判断何时应该继续“思考-行动”，何时任务完成或失败需要终止。

一个简化的运行时循环伪代码如下：

class AgentRuntime: def __init__(self, skills, memory, planner=None): self.skills = skills # 技能库 self.memory = memory # 记忆模块 self.planner = planner # 规划器（可选） self.state = {} async def run(self, user_input: str): # 初始化状态 self.state = {"goal": user_input, "steps": [], "observation": None} # 可选：调用规划器分解任务 if self.planner: plan = await self.planner.plan(user_input) self.state["plan"] = plan # 可能将大任务转化为一系列子任务状态机 max_steps = 10 for step in range(max_steps): # 1. 组装提示词（包含目标、历史、可用工具、当前观察等） prompt = self._assemble_prompt(self.state) # 2. 调用大模型 llm_response = await self.llm_client.generate(prompt) # 3. 解析输出 parsed = self._parse_llm_response(llm_response) # parsed 可能包含：{'thought': '...', 'action': {'tool': 'get_weather', 'input': {'city': '北京'}}} # 或者 {'final_answer': '...'} # 4. 判断是否为最终答案 if 'final_answer' in parsed: self.state['final_answer'] = parsed['final_answer'] await self.memory.save_episode(self.state) # 保存完整经历到记忆 return parsed['final_answer'] # 5. 执行动作（工具调用） action = parsed['action'] skill = self._find_skill(action['tool']) if skill: try: result = await skill.execute(action['input']) self.state['observation'] = f"工具 {action['tool']} 执行成功: {result}" except Exception as e: self.state['observation'] = f"工具 {action['tool']} 执行失败: {str(e)}" else: self.state['observation'] = f"未知工具: {action['tool']}" # 6. 记录步骤 self.state['steps'].append({ 'thought': parsed.get('thought'), 'action': action, 'observation': self.state['observation'] }) # 7. 可选：进行反思 if step % 3 == 0: # 每3步反思一次 reflection = await self._trigger_reflection(self.state) self.memory.add_reflection(reflection) # 循环超过最大步数，任务失败 return "任务执行超时，未能完成。"

3.3 模式的具体实现与组合

项目中的“Patterns”很可能就是上述运行时的一种种预配置和扩展。例如：

• ReAct Pattern:可能是一个已经实现了上述主循环的ReActRuntime类，开发者只需要注入技能和记忆即可使用。
• Plan-and-Execute Pattern:可能是一个组合了PlannerAgent和ReActRuntime的PlanAndExecuteRuntime。PlannerAgent先生成子任务列表，然后为每个子任务启动一个ReActRuntime实例（或复用同一个）来执行。
• Reflection Pattern:可能是一个ReflectionSkill本身，它接收一段执行历史作为输入，输出反思总结。这个技能可以被编排到运行时循环的特定节点中自动调用。

这种设计使得模式像乐高积木一样可以组合。你可以创建一个使用“向量记忆”的“带反思的ReAct智能体”，也可以创建一个先规划、再对每个子任务进行带反思执行的复杂智能体。

4. 实战：构建一个旅行规划智能体

理论说得再多，不如动手实践。让我们利用从agentic-harness-patterns-skill项目中汲取的设计思想，从头开始构建一个简单的“旅行规划智能体”。这个智能体能够理解用户模糊的需求（如“我想去云南玩5天，预算5000元”），并输出一个详细的行程计划。

4.1 定义核心技能（Skills）

首先，我们需要定义智能体可以调用的技能。这些技能是它感知和影响外部世界的“手脚”。

1. 目的地信息查询技能（query_destination_info）:

   • 描述：获取某个旅游目的地的基本信息，如热门景点、特色美食、最佳旅行季节、注意事项等。
   • 实现：可以对接一个旅游知识库API，或者在一个本地数据库/JSON文件中查询。为简化，我们可以预设一个字典来存储几个目的地的信息。

2. 天气查询技能（get_weather）:

   • 描述：查询指定城市在未来某段时间的天气预报。
   • 实现：调用公开的天气API（如和风天气、OpenWeatherMap）。需要处理API密钥和网络请求。

3. 预算估算技能（estimate_budget）:

   • 描述：根据目的地、天数、人数、住宿和交通偏好，粗略估算旅行预算。
   • 实现：可以基于一些规则或历史数据来计算。例如，目的地消费等级 x 天数 + 往返交通费。

4. 行程大纲生成技能（generate_itinerary_outline）:

   • 描述：根据目的地、天数、兴趣点（如自然风光、历史文化、美食），生成一个按天划分的行程大纲。
   • 实现：这个技能本身就可以是一个“小智能体”或利用大模型的生成能力。输入是结构化的需求，输出是Markdown格式的行程草案。

4.2 设计智能体工作流（Patterns组合）

对于旅行规划这个复杂任务，单一的ReAct循环可能不够高效。我们采用“规划-执行-细化”的组合模式。

1. 规划阶段（Planner）：

   • 创建一个PlannerAgent，其提示词要求它分析用户请求，并输出一个JSON格式的规划，包括需要调用的技能序列和初步信息。
   • 例如，对于“云南5日游，预算5000”，规划器可能输出：

     { "sub_tasks": [ {"skill": "query_destination_info", "input": {"destination": "云南"}, "purpose": "了解云南整体情况和热门城市"}, {"skill": "get_weather", "input": {"city": "昆明", "days": 5}, "purpose": "查看昆明近期天气"}, {"skill": "estimate_budget", "input": {"destination": "云南", "days": 5, "budget_constraint": 5000}, "purpose": "评估预算可行性"}, {"skill": "generate_itinerary_outline", "input": {"destination": "云南", "days": 5, "interests": ["自然风光", "少数民族文化"]}, "purpose": "生成初步行程"} ] }

2. 执行阶段（Executor - ReAct）：

   • 针对规划器生成的每一个sub_task，启动一个标准的ReAct循环来执行。但这里的“行动”被限定为调用指定的那个技能。
   • 这个阶段主要是收集信息。每个技能执行后，其结果会被汇总到中央状态中。

3. 细化与生成阶段（Synthesizer）：

   • 所有子任务执行完毕后，我们拥有了目的地信息、天气、预算评估和初步行程大纲。
   • 此时，再调用一次大模型（可以看作一个SynthesisSkill），将前面收集的所有碎片化信息作为上下文，要求它生成一份完整、连贯、人性化的最终旅行计划，包括每日详细安排、交通建议、住宿推荐、预算分项和注意事项。

4.3 代码实现要点与核心片段

下面展示一些关键部分的简化代码，以说明如何将上述设计串联起来。

首先，定义技能基类和注册表：

import json from abc import ABC, abstractmethod from typing import Any, Dict from pydantic import BaseModel class Skill(ABC): """技能基类""" name: str description: str input_schema: type[BaseModel] @abstractmethod async def execute(self, input_data: Dict[str, Any]) -> Any: pass class SkillRegistry: """技能注册表""" def __init__(self): self._skills = {} def register(self, skill: Skill): self._skills[skill.name] = skill def get(self, name: str) -> Skill: return self._skills.get(name) def list_descriptions(self) -> str: """生成给LLM看的工具描述列表""" desc_list = [] for name, skill in self._skills.items(): desc_list.append(f"- {name}: {skill.description} 输入格式示例: {skill.input_schema.schema_json()}") return "\n".join(desc_list) # 实例化注册表 registry = SkillRegistry()

接着，实现一个具体的技能（以查询目的地为例）：

class DestinationQueryInput(BaseModel): destination: str class DestinationQueryOutput(BaseModel): intro: str hot_cities: list best_season: str tips: str class QueryDestinationSkill(Skill): name = "query_destination_info" description = "查询旅游目的地的基本信息，包括介绍、热门城市、最佳季节和旅行提示。" input_schema = DestinationQueryInput async def execute(self, input_data: Dict[str, Any]) -> DestinationQueryOutput: # 这里应该是真实的API或数据库调用，此处为模拟数据 data_map = { "云南": DestinationQueryOutput( intro="云南位于中国西南，以丰富的民族文化、多样的自然景观和宜人的气候闻名。", hot_cities=["昆明", "大理", "丽江", "西双版纳", "香格里拉"], best_season="春季（3-5月）和秋季（9-11月）", tips="注意高原反应，尊重当地少数民族风俗，温差较大需备衣物。" ), # ... 其他目的地 } dest = input_data.get("destination", "") return data_map.get(dest, DestinationQueryOutput(intro="信息暂缺", hot_cities=[], best_season="", tips="")) # 注册技能 registry.register(QueryDestinationSkill())

然后，实现一个简化的ReAct运行时：

class SimpleReActRuntime: def __init__(self, skill_registry: SkillRegistry, llm_client): self.registry = skill_registry self.llm = llm_client self.max_turns = 6 async def run_for_task(self, task_description: str, available_skills_desc: str) -> str: """针对一个明确子任务运行ReAct循环""" prompt_template = f""" 你是一个任务执行助手。你的目标：{task_description} 你可以使用以下工具： {available_skills_desc} 请严格按照以下格式回应： Thought: [你下一步的思考] Action: [要调用的工具名，必须是上述工具之一。输入应为JSON格式，与工具要求匹配。] 或者，如果你认为任务已经完成，可以输出： Final Answer: [最终的回答] 现在开始。当前目标：{task_description} """ history = [] for i in range(self.max_turns): # 组装包含历史的提示词 full_prompt = prompt_template for h in history: full_prompt += f"\n{h}" response = await self.llm.generate(full_prompt) # 解析响应 (这里需要健壮的解析器，简化为字符串匹配) if "Final Answer:" in response: return response.split("Final Answer:")[1].strip() # 解析 Thought 和 Action thought = "" action_line = "" lines = response.split('\n') for line in lines: if line.startswith('Thought:'): thought = line[8:].strip() elif line.startswith('Action:'): action_line = line[7:].strip() if not action_line: history.append(f"助手响应格式错误: {response}") continue # 解析工具名和输入 try: tool_name, json_str = action_line.split(':', 1) tool_name = tool_name.strip() input_dict = json.loads(json_str.strip()) except (ValueError, json.JSONDecodeError) as e: history.append(f"动作解析失败: {action_line}, 错误: {e}") continue # 执行工具 skill = self.registry.get(tool_name) if not skill: obs = f"未知工具: {tool_name}" else: try: result = await skill.execute(input_dict) obs = f"工具 {tool_name} 返回: {result}" except Exception as e: obs = f"工具 {tool_name} 执行出错: {str(e)}" # 记录到历史 history.append(f"Thought: {thought}\nAction: {action_line}\nObservation: {obs}") return "子任务执行超时，未完成。"

最后，组合成规划与执行工作流：

class TravelPlannerAgent: def __init__(self, skill_registry, llm_client): self.registry = skill_registry self.llm = llm_client self.react_runtime = SimpleReActRuntime(skill_registry, llm_client) async def plan(self, user_request: str) -> list: """规划阶段：将用户请求分解为子任务""" planner_prompt = f""" 用户请求：{user_request} 请将该旅行规划请求分解为一系列具体的查询或生成任务。 以JSON列表格式输出，每个元素是一个子任务对象，包含字段： - "skill": 要使用的技能名（必须是以下之一：{', '.join([s.name for s in self.registry._skills.values()])}） - "input": 该技能需要的输入参数（JSON对象） - "purpose": 该子任务的目的说明 """ plan_response = await self.llm.generate(planner_prompt) # 此处需要解析JSON，实际应用中需添加错误处理 import ast try: sub_tasks = json.loads(plan_response) except: # 如果LLM没返回标准JSON，尝试用其他方法提取或使用默认计划 sub_tasks = [{"skill": "query_destination_info", "input": {"destination": "云南"}, "purpose": "了解目的地"}] return sub_tasks async def execute_plan(self, sub_tasks: list) -> Dict[str, Any]: """执行阶段：运行所有子任务，收集结果""" results = {} for task in sub_tasks: skill_name = task["skill"] task_desc = f"{task['purpose']} 使用技能 {skill_name}。" # 为每个子任务运行ReAct循环 result = await self.react_runtime.run_for_task(task_desc, self.registry.list_descriptions()) results[skill_name] = result return results async def synthesize(self, user_request: str, collected_results: Dict[str, Any]) -> str: """生成阶段：综合所有信息，形成最终计划""" synthesis_prompt = f""" 用户原始请求：{user_request} 在规划过程中，我们收集了以下信息： {json.dumps(collected_results, indent=2, ensure_ascii=False)} 请基于以上所有信息，生成一份详细、实用、吸引人的旅行计划书。 计划书应包含：行程概述、每日详细安排（时间、地点、活动、餐饮建议）、交通指南、住宿推荐、预算分配清单、必备物品和注意事项。 请用Markdown格式输出，确保内容结构清晰、信息完整。 """ final_plan = await self.llm.generate(synthesis_prompt) return final_plan async def run(self, user_request: str) -> str: """主流程""" print("1. 规划阶段...") sub_tasks = await self.plan(user_request) print(f" 生成子任务: {sub_tasks}") print("2. 执行阶段...") collected_data = await self.execute_plan(sub_tasks) print(f" 收集到数据: {list(collected_data.keys())}") print("3. 生成最终计划...") final_output = await self.synthesize(user_request, collected_data) return final_output # 使用示例 async def main(): planner = TravelPlannerAgent(registry, your_llm_client) # 需要传入真实的LLM客户端 plan = await planner.run("我想在11月去云南玩5天，预算5000元左右，喜欢自然风光和美食。") print(plan)

注意事项：以上代码是高度简化的概念演示。在实际项目中，你需要处理许多边缘情况，比如LLM输出格式不稳定、技能执行失败的重试机制、更复杂的状态管理、异步并发执行子任务以提升效率、以及更完善的错误处理和日志记录。此外，提示词工程需要大量调试和优化，才能让智能体可靠地遵循格式并做出合理决策。

5. 高级技巧、优化方向与避坑指南

基于agentic-harness-patterns-skill这类项目的思想构建智能体应用时，除了基础实现，还有很多高级技巧和优化方向可以大幅提升系统的性能和可靠性。

5.1 提示词工程的高级策略

提示词是智能体的“灵魂”。好的提示词能极大地提升模型的输出质量和稳定性。

1. 少样本学习（Few-shot Learning）：在提示词中提供2-3个高质量的输入输出示例，能显著引导模型遵循你期望的格式和推理路径。对于ReAct模式，示例应展示完整的“Thought-Action-Observation”循环。
2. 思维链（Chain-of-Thought）提示：鼓励模型展示其推理步骤。对于规划类任务，可以在提示词中要求模型“让我们一步步思考”，这通常能产生更逻辑严谨的规划。
3. 输出格式约束：明确要求模型以特定格式（JSON、XML、Markdown列表）输出，并可在后续代码中通过解析器进行强校验。对于JSON，甚至可以提供JSON Schema。
4. 角色扮演与系统指令：为模型设定一个明确的角色（如“你是一位资深的旅行规划专家”），并给出系统层面的行为指令（如“始终以用户预算为第一考量”、“确保行程安排松紧适度”），这能更好地塑造智能体的行为风格。

5.2 性能与成本优化

智能体应用频繁调用LLM，成本和延迟是需要重点考虑的问题。

1. 缓存：对频繁出现的、结果固定的查询（如“北京有哪些景点？”）进行缓存。可以使用内存缓存（如functools.lru_cache）或分布式缓存（如Redis）。缓存键应基于技能名和输入参数的哈希。
2. 异步并发：当多个子任务之间没有依赖关系时，使用asyncio.gather等机制并发执行，可以大幅缩短总执行时间。
3. 模型分级：并非所有步骤都需要最强大、最昂贵的模型。例如，工具调用的解析和路由可以使用更小、更快的模型（如gpt-3.5-turbo），而最终的总结、创作等需要高质量输出的步骤再用大模型（如gpt-4）。agentic-harness-patterns-skill的模式设计应支持为不同环节配置不同的LLM。
4. 上下文管理：精打细算地使用上下文窗口。只将最相关的历史对话、记忆片段放入提示词。对长历史进行摘要（Summarization），而不是全部堆进去。

5.3 可靠性提升与错误处理

智能体在开放环境中运行，必须健壮。

1. 结构化输出解析的鲁棒性：模型输出不总是完美的JSON。需要编写容错性强的解析器，可以尝试：
   • 使用json.loads()并捕获异常，失败后尝试用正则表达式提取关键字段。
   • 使用专门库如instructor或Pydantic配合LLM调用，强制输出结构化数据。
   • 在提示词中强调“必须输出纯JSON，不要有任何额外解释”。
2. 技能调用的错误处理与重试：
   • 为每个技能调用添加超时（timeout）设置。
   • 实现指数退避（exponential backoff）的重试机制，应对网络波动或API限流。
   • 技能执行失败时，将清晰的错误信息作为“Observation”返回给智能体，让它有机会调整策略（例如，“查询航班失败，原因是日期格式错误。请确保日期格式为YYYY-MM-DD”）。
3. 循环超时与中断：必须为ReAct等循环设置最大步数（max steps），防止智能体陷入无限循环或在不重要的问题上钻牛角尖。当达到上限时，优雅终止并返回当前最佳结果或错误信息。
4. 验证与护栏（Guardrails）：在智能体输出最终答案给用户前，可以增加一个“验证”步骤。例如，用一个简单的规则或另一个轻量级模型检查输出中是否包含不安全、不道德或与事实严重不符的内容。

5.4 评估与持续改进

如何知道你的智能体是否在变好？

1. 定义评估指标：根据应用场景定义关键指标。例如，对于旅行规划智能体，指标可以包括：行程合理性评分、信息准确率、用户满意度（通过反馈收集）、任务完成率、平均交互轮次等。
2. 构建测试集：准备一批覆盖各种场景（简单、复杂、边缘情况）的测试用例。每次对智能体或提示词做出重大修改后，运行测试集来评估效果是提升还是下降。
3. 日志与追踪：记录每一次智能体运行的完整轨迹，包括所有的提示词、模型响应、工具调用和结果。这不仅是调试的宝贵资料，也是后续进行反思学习、构建高质量数据集的来源。可以考虑集成像LangSmith这样的AI应用追踪平台。
4. 利用反思进行自我改进：实现一个离线过程，定期将失败的或低质量的运行轨迹喂给一个更强大的模型（如GPT-4），让它分析失败原因并提出改进建议（例如，如何优化提示词、是否需要增加新技能）。这可以形成一个自我完善的闭环。

构建一个成熟的智能体系统是一个迭代过程。keli-wen/agentic-harness-patterns-skill这类项目提供的模式是优秀的起点和工具箱，但真正的挑战在于如何将这些模式与你特定的业务逻辑、领域知识结合起来，并通过持续的提示词优化、技能扩展和架构调整，打造出真正实用、可靠、智能的AI应用。