1. 项目概述：从“能用”到“好用”的Agent工程实践

最近在折腾一个基于大语言模型的智能体项目，从最初的简单问答，到后来引入工具调用，再到现在的多轮对话和复杂任务规划，一路踩坑无数。当项目代号走到“12”这个节点时，我意识到，一个真正“好用”的Agent，远不止是模型API的简单封装。它需要像一位经验丰富的同事，能感知任务状态、能接受引导、能实时反馈、还能在完成后给出清晰的总结。这恰恰对应了标题中的四个核心议题：Hook补充、控制Agent、流式输出和总结。这四项能力，是将一个“玩具级”Demo升级为“生产级”应用的关键跨越。

如果你也在构建自己的AI助手、自动化工作流或者复杂的决策系统，那么理解如何为Agent植入这些“高级能力”，将是提升用户体验和系统可靠性的必修课。本文将结合我最近在一个客户服务自动化项目中的实战经验，拆解这四大模块的实现思路、技术细节以及那些在官方文档里找不到的“坑”与“技巧”。我们会从最基础的Hook机制讲起，逐步深入到如何像“牵线木偶”一样精细控制Agent的行为，再探讨让交互体验丝滑的流式输出，最后完成高质量的任务总结。整个过程，我们将使用主流的LangChain框架和OpenAI API作为示例，但其中的设计思想和解决方案是跨平台通用的。

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

2.1 Hook机制：为Agent注入“感知神经”

Hook，中文常译为“钩子”或“回调”，是软件工程中实现事件驱动和可扩展性的经典模式。在Agent的上下文中，Hook就是我们在Agent执行生命周期的关键节点（如开始、结束、调用工具前、调用工具后、产生最终答案前）插入的自定义代码逻辑。你可以把它想象成在Agent的“神经系统”上安装的传感器和控制器。

为什么需要Hook？没有Hook的Agent就像一个黑盒，你输入问题，它输出答案，中间过程一无所知。这在调试、监控、审计和实现复杂逻辑（如权限校验、成本控制、流程中断）时是致命的。例如，在一个处理财务数据的Agent中，你必须在它调用“数据库查询工具”前，Hook进去验证用户的查询权限；在它每次调用昂贵的模型API后，Hook进去记录Token消耗以控制成本。

核心Hook类型与实战场景：

1. on_chain_start/end: 当Agent开始或结束一个完整的推理链（Chain）时触发。适用于全局性的资源初始化（如连接数据库）和清理（如关闭连接、发送执行报告）。
2. on_tool_start/end: 在Agent准备调用一个工具（Tool）以及工具执行完毕后触发。这是最常用的Hook，用于：
   • 输入校验与过滤：检查工具输入参数是否安全、合规。
   • 执行监控：记录工具调用的耗时、成功与否。
   • 结果后处理：对工具返回的原始数据（如一大段JSON）进行清洗、格式化或摘要，再交给Agent，能极大提升后续推理的效率和准确性。
3. on_llm_start/end: 在大语言模型（LLM）被调用前后触发。主要用于：
   • Prompt工程监控：记录实际发送给模型的Prompt，用于分析和优化。
   • 响应劫持与修改：在模型输出最终答案前，对其内容进行合规性检查、敏感词过滤或格式标准化。
   • 流式处理对接：这是实现流式输出的关键技术入口，我们会在第三部分详细展开。

在我的项目中，我建立了一个统一的AgentMonitor类来管理所有Hook。它不仅仅记录日志，更实现了“熔断”机制：当on_tool_startHook检测到连续3次工具调用失败，或on_llm_startHook发现本次请求预估Token成本超过阈值，会主动抛出异常，中断Agent执行，避免陷入死循环或产生意外费用。

实操心得：Hook的注册顺序很重要！LangChain等框架通常按照注册顺序执行Hook。如果你有一个用于数据脱敏的Hook和一个用于日志记录的Hook，一定要先注册脱敏Hook，确保日志里记录的是脱敏后的安全数据。

2.2 控制Agent：从“自动驾驶”到“人机共驾”

让Agent完全自主运行（自动驾驶）在复杂场景下风险很高。控制Agent的核心思想是引入“人机共驾”模式，在关键决策点将控制权交还给用户或上层系统。这主要通过两种方式实现：流程控制和输入引导。

2.2.1 流程控制：给Agent装上“方向盘和刹车”

流程控制关注的是Agent的执行路径。我们通过Hook和自定义逻辑，主动干预其工作流。

• 中断与继续：在on_tool_startHook中，我们可以检查工具执行的前提条件。例如，一个“发送邮件”的工具需要确认收件人。如果条件不满足，我们可以暂停Agent，通过一个预设的渠道（如弹出对话框、发送消息到消息队列）向用户请求确认信息，待用户回复后，再将信息注入Agent上下文，让其继续执行。这实现了“询问-确认”式交互。
• 分支选择：Agent在规划步骤时，可能会生成多个潜在路径。我们可以在on_chain_end时解析其思维链（Chain-of-Thought），将不同的计划选项呈现给用户选择。例如，处理“分析本月销售数据”的任务，Agent可能规划路径A“先查询数据库，再做图表”，路径B“先调用Python进行数据清洗，再分析”。我们可以拦截这个规划，让用户决定走哪条路。
• 超时与重试：在Agent执行外层包裹超时控制逻辑。如果整个Agent运行超过设定时间（如2分钟），则强制终止，并尝试总结已完成的局部成果，或转入降级处理流程。

2.2.2 输入引导：用Prompt和上下文“设定航向”

这是更常用、更精细的控制方式，通过设计系统提示词（System Prompt）和管理对话历史（Memory）来影响Agent的“思考”。

• 角色与边界设定：在System Prompt中明确Agent的角色、职责和禁忌。例如：“你是一个谨慎的金融数据分析助手，在给出任何涉及具体金额的投资建议前，必须首先调用‘风险核查工具’评估用户风险等级，并且你的所有输出都不能包含对未来股价的具体预测。”
• 逐步审批模式：对于高风险操作，可以指令Agent将复杂任务分解为极小的步骤，每执行一步都输出当前状态和下一步计划，等待外部系统的“批准”指令后再继续。这可以通过在Prompt中要求Agent输出特定格式（如【步骤完成】...【下一步待批准】...）来实现，再由外部程序解析并控制。
• 上下文管理：主动管理提供给Agent的对话历史。选择性遗忘无关历史，或手动插入关键引导信息。例如，当用户说“用刚才那个思路再做一遍”时，程序需要自动从历史中提取出“刚才那个思路”的具体内容，并将其作为上下文插入新一轮的请求中。

在我的客户服务项目中，我们实现了“专家坐席接管”功能。当自主Agent在对话中检测到用户情绪关键词（如“投诉”、“不满意”）或连续两轮未能解决问题时，会触发一个Hook，该Hook会改变后续的System Prompt，将Agent角色从“自主解决问题”切换为“收集信息并转交人类”，同时向后台系统发送警报。这就是一种典型的基于事件和Hook的流程控制。

2.3 流式输出：打造“正在思考”的实时体验

流式输出（Streaming）对于提升交互体验至关重要。它让用户看到Agent“一个字一个字”地生成回答，而不是面对一个长时间的空白等待后突然出现大段文字。这种实时反馈传达了“系统正在努力为你工作”的信号，极大地减轻了等待的焦虑感。

技术本质：大语言模型的生成本质上是逐词（Token）预测的。流式输出就是利用服务器发送事件（Server-Sent Events, SSE）或WebSocket等技术，将这个逐词生成的过程实时地推送到前端。

实现层次与难点：

1. LLM原生流式：大多数云厂商的LLM API（如OpenAI, Anthropic）都支持流式响应。你只需要在调用时设置stream=True参数，API就会返回一个数据流。这是基础。
2. Agent层面的流式：这是真正的难点。一个Agent的完整输出可能包含：它的“思考过程”（“我先要查一下天气，然后...”）、“工具调用”（Action: search_weather, Action Input: {"city": "北京"}）、“工具结果”（Observation: 北京今天晴，25度）以及“最终答案”。我们需要将这些不同性质的内容都流式化，并以一种结构化的方式呈现给前端。

解决方案：我们需要利用LangChain的CallbackHandler机制，特别是为流式场景设计的AstraStreamingCallbackHandler或其自定义变体。核心思路是创建自定义的StreamingCallbackHandler，在其on_llm_new_token方法中，将每一个新生成的Token通过消息队列或直接向前端推送。但更重要的是，我们还需要在on_chain_start/end、on_tool_start/end等Hook中，推送非Token的“事件消息”。

例如：

• 当Agent开始思考：推送事件{"event": "agent_think", "data": "开始规划任务..."}
• 当Agent决定调用工具：推送事件{"event": "agent_action", "data": {"tool": "search", "input": "xxx"}}
• 当工具返回结果：推送事件{"event": "tool_result", "data": "查询结果：..."}
• 当LLM生成最终答案的每一个Token：通过on_llm_new_token推送Token流。

前端则需要根据这些不同的事件类型，以不同的UI形式（如思考气泡、工具调用卡片、结果区块、流动文字）来渲染，从而完整再现Agent的推理和执行流水线。

踩坑实录：直接混流所有内容（思考、动作、结果、答案）到一个字符串流里，前端解析会非常混乱。务必设计一个轻量级的协议（如上述的简单JSON结构），将“元事件”和“内容流”分开传输。此外，网络中断和重连下的流式恢复是个复杂问题，通常需要在服务端缓存一定量的上下文，并在重连时发送一个包含最近事件和状态的“快照”。

2.4 总结生成：从过程流水账到价值简报

Agent完成一系列复杂操作后，直接给用户扔过来一堆工具调用记录和模型生成的原始文本，体验是非常糟糕的。总结（Summarization）模块的作用，就是将冗长、琐碎的执行过程，提炼成一份清晰、有价值、面向用户的简报。

总结什么？

1. 执行过程摘要：用一两句话说明Agent为了完成任务，做了哪几件关键事情。例如：“本次查询为您完成了以下操作：首先检索了截至昨日的A公司股价数据，然后计算了其近一周的波动率，最后与行业指数进行了对比分析。”
2. 关键结果呈现：直接给出用户最关心的核心结果或数据结论，而不是中间步骤。例如：“分析结论：A公司股价近期波动率（3.2%）高于行业平均（2.1%），需关注其风险。”
3. 后续建议或问题：基于执行过程，提出下一步的行动建议或澄清性问题。例如：“已为您生成报告。需要注意的是，所用数据截至昨日，如需今日实时数据，请确认后我可再次查询。” 或者 “在计算过程中，发现B数据项存在缺失，这可能影响分析的准确性。”

如何生成？

• LLM驱动总结：这是最灵活、效果最好的方式。将Agent的完整执行轨迹（包括它的思考、调用的工具、工具返回的结果）作为上下文，发送给LLM，并设计一个专门的Prompt指令其进行总结。例如：“你是一个助手。以下是你刚才为解决用户问题所执行的全部操作记录。请根据这些记录，生成一段面向用户的、简洁友好的任务总结，需包含主要步骤和核心结果。”
• 模板化总结：对于流程固定、结构清晰的任务，可以设计总结模板。通过解析执行历史，提取关键变量（如工具名、结果中的数值）填充到模板中。这种方式速度快、成本低，但灵活性差。
• 混合模式：先通过规则提取关键数据点（如工具调用次数、最终答案），再将这些结构化信息连同部分历史一起交给LLM，让其组织成自然语言。这在平衡成本与效果时很有效。

在我的项目中，总结模块被做成了一个可插拔的“后处理器”。它订阅Agent的on_chain_end事件，接收到完整的运行轨迹后，会启动一个独立的、配置了更低成本模型（如GPT-3.5-Turbo）的LLM链来生成总结。生成后的总结会与Agent的原始输出一起，返回给用户。同时，这个总结也会被存储到数据库，作为本次会话的“快照”，便于日后审计和复查。

3. 实战集成：构建一个具备完整能力的Agent系统

理论讲完了，我们来动手搭建一个具备Hook、控制、流式输出和总结功能的简易Agent系统。我们将以“一个能联网搜索并总结新闻的Agent”为例。

3.1 系统架构与核心组件定义

首先，我们规划整个系统的数据流：用户请求进入 -> 被主Agent处理（期间触发各类Hook）-> 流式事件和最终答案被推送到前端 -> 任务结束后触发总结生成器 -> 总结返回给用户。

我们定义几个核心类：

1. CustomStreamingCallbackHandler: 继承自BaseCallbackHandler，负责处理流式输出和事件推送。
2. AgentController: 封装Agent实例，并注册各种Hook，提供控制接口（如暂停、继续、注入信息）。
3. Summarizer: 总结生成模块。
4. App: 主应用，集成上述组件，处理Web请求。

3.2 分步实现与代码详解

步骤1：构建工具和Agent我们首先需要一个搜索工具，并使用LangChain的React框架来创建基础Agent。

import os from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain_community.utilities import SerpAPIWrapper from langchain_openai import ChatOpenAI # 1. 定义搜索工具 search = SerpAPIWrapper(serpapi_api_key=os.getenv("SERPAPI_KEY")) tools = [ Tool( name="Search", func=search.run, description="用于搜索互联网上的最新信息。当需要获取实时、事实性信息时使用此工具。" ) ] # 2. 初始化LLM llm = ChatOpenAI(model="gpt-4", temperature=0, streaming=True) # 注意开启streaming支持 # 3. 定义Prompt模板（包含控制指令） from langchain import hub prompt = hub.pull("hwchase17/react") # 我们可以修改prompt，加入控制指令，例如： # prompt.template = prompt.template + "\n请注意：在执行任何可能具有外部影响的操作（如发送信息）前，请先输出'[PAUSE_FOR_APPROVAL]'并等待。" # 4. 创建基础Agent agent = create_react_agent(llm, tools, prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True)

步骤2：实现自定义流式回调处理器这是实现流式输出的核心。我们将同时处理Token流和自定义事件。

from langchain.callbacks.base import BaseCallbackHandler import json class CustomStreamingCallbackHandler(BaseCallbackHandler): """自定义回调处理器，用于推送流式事件和Token。""" def __init__(self, queue): super().__init__() self.queue = queue # 假设是一个asyncio.Queue或类似的消息队列，用于向前端推送 def on_chain_start(self, serialized, inputs, **kwargs): """链开始事件""" event_data = {"event": "chain_start", "data": f"开始处理任务: {inputs.get('input', '')[:50]}..."} self.queue.put_nowait(json.dumps(event_data)) def on_tool_start(self, serialized, input_str, **kwargs): """工具开始调用事件""" # 这里可以解析出工具名 tool_name = serialized.get('name', 'Unknown Tool') event_data = {"event": "tool_start", "data": {"tool": tool_name, "input": input_str}} self.queue.put_nowait(json.dumps(event_data)) def on_tool_end(self, output, **kwargs): """工具调用结束事件""" # 输出可能很长，我们只发送摘要或前一部分 output_preview = str(output)[:200] + "..." if len(str(output)) > 200 else str(output) event_data = {"event": "tool_end", "data": {"output": output_preview}} self.queue.put_nowait(json.dumps(event_data)) def on_llm_new_token(self, token: str, **kwargs): """LLM生成新Token事件 - 核心流式输出""" event_data = {"event": "llm_new_token", "data": token} self.queue.put_nowait(json.dumps(event_data)) def on_chain_end(self, outputs, **kwargs): """链结束事件，触发总结""" event_data = {"event": "chain_end", "data": "任务执行流结束，即将生成总结..."} self.queue.put_nowait(json.dumps(event_data)) # 注意：实际总结生成可能异步进行，这里只是通知事件流结束

步骤3：构建Agent控制器与总结器我们将Hook注册、流程控制和总结逻辑封装起来。

class AgentController: def __init__(self, agent_executor, callback_handler): self.agent_executor = agent_executor self.callback_handler = callback_handler # 可以在这里注册更多的Hook，例如用于权限校验的Hook self._register_hooks() def _register_hooks(self): # LangChain的AgentExecutor在初始化时可以通过callbacks参数传入回调处理器 # 我们这里主要依赖传入的callback_handler pass async def run(self, user_input: str, context: dict = None): """运行Agent，并返回最终结果和总结""" # 准备输入，可以加入上下文 inputs = {"input": user_input} if context: inputs.update(context) try: # 执行Agent，传入回调处理器以启用流式输出和事件捕获 raw_output = await self.agent_executor.ainvoke( inputs, config={"callbacks": [self.callback_handler]} ) final_answer = raw_output.get("output", "No output generated.") # 触发异步总结生成 summary = await Summarizer.generate_summary(raw_output) return { "final_answer": final_answer, "summary": summary, "status": "success" } except Exception as e: # 错误处理，也可以通过callback_handler推送错误事件 error_event = {"event": "error", "data": str(e)} self.callback_handler.queue.put_nowait(json.dumps(error_event)) return {"status": "error", "message": str(e)} class Summarizer: @staticmethod async def generate_summary(agent_run_output: dict): """根据Agent运行输出生成总结""" # 这里简化处理，实际中应该调用一个专门的LLM链 # 1. 提取关键信息：工具调用记录、最终答案等 history = agent_run_output.get("intermediate_steps", []) final_answer = agent_run_output.get("output", "") # 2. 构建总结Prompt（简化版） summary_prompt = f""" 你是一个助手。以下是你刚才为解决用户问题所执行的操作记录和最终答案。 操作历史：{history} 最终给出的答案：{final_answer} 请用一段话（不超过3句）向用户总结你刚才做了什么，并突出核心结果。语气要友好、简洁。 总结： """ # 3. 调用LLM生成总结（可以使用一个更轻量、更便宜的模型） # 这里为示例，直接模拟一个结果 # 实际代码中，你需要初始化另一个LLM并调用 # summary_llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) # summary = await summary_llm.ainvoke(summary_prompt) simulated_summary = f"我已为您搜索并整理了相关信息。核心结论是：{final_answer[:100]}...（详情见上方完整回答）。" return simulated_summary

步骤4：组装主应用（FastAPI示例）最后，我们用Web框架将一切连接起来，提供一个HTTP接口。

from fastapi import FastAPI, HTTPException from fastapi.responses import StreamingResponse import asyncio import json app = FastAPI() # 全局组件（生产环境应使用依赖注入） callback_queue = asyncio.Queue() stream_handler = CustomStreamingCallbackHandler(callback_queue) controller = AgentController(agent_executor, stream_handler) async def event_generator(queue): """异步生成器，从队列中取出事件并推送给客户端""" try: while True: event = await queue.get() if event is None: # 收到结束信号 break # 格式化为SSE数据格式 yield f"data: {event}\n\n" queue.task_done() except asyncio.CancelledError: print("客户端断开连接") @app.post("/chat/stream") async def chat_stream(user_input: str): """流式聊天接口""" async def run_agent_and_stream(): # 启动一个后台任务来执行Agent agent_task = asyncio.create_task(controller.run(user_input)) # 同时，将事件生成器返回给客户端 async for event in event_generator(callback_queue): yield event # 等待Agent任务完成，获取最终结果和总结 result = await agent_task # 发送最终结果和总结作为特殊事件 final_event = { "event": "final_result", "data": { "answer": result.get("final_answer", ""), "summary": result.get("summary", "") } } yield f"data: {json.dumps(final_event)}\n\n" # 发送流结束信号 yield f"data: [DONE]\n\n" return StreamingResponse( run_agent_and_stream(), media_type="text/event-stream", headers={ 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', 'X-Accel-Buffering': 'no' # 禁用Nginx缓冲 } )

3.3 前端简易示例（SSE客户端）

前端需要能够接收并解析SSE事件流。

// 前端JavaScript示例 (使用EventSource) const eventSource = new EventSource('/chat/stream?user_input=北京今天的天气怎么样？'); eventSource.onmessage = (event) => { const data = JSON.parse(event.data); switch(data.event) { case 'chain_start': console.log(`任务开始: ${data.data}`); // 在UI上显示“任务开始”状态 break; case 'tool_start': console.log(`调用工具: ${data.data.tool}， 输入: ${data.data.input}`); // 在UI上显示一个工具调用卡片 break; case 'tool_end': console.log(`工具结果: ${data.data.output}`); // 更新工具调用卡片，显示结果 break; case 'llm_new_token': // 这是流式文本，逐个Token追加到答案区域 document.getElementById('answer-area').innerHTML += data.data; break; case 'chain_end': console.log('任务执行流结束'); break; case 'final_result': console.log('最终答案:', data.data.answer); console.log('任务总结:', data.data.summary); // 在UI的总结区域显示总结 document.getElementById('summary-area').innerText = data.data.summary; eventSource.close(); // 关闭连接 break; case 'error': console.error('发生错误:', data.data); eventSource.close(); break; default: console.log('未知事件:', data); } }; eventSource.onerror = (err) => { console.error('EventSource failed:', err); eventSource.close(); };

4. 避坑指南与性能优化实录

在实际开发和上线过程中，我遇到了不少棘手的问题。这里分享几个最具代表性的“坑”及其解决方案。

4.1 Hook执行顺序与状态管理混乱

问题描述：早期版本中，我注册了多个Hook：一个用于日志记录（Hook A），一个用于数据脱敏（Hook B）。结果发现日志里记录的仍然是脱敏前的原始数据，存在安全风险。这是因为Hook的执行顺序依赖于注册顺序，而我先注册了A，后注册了B。

解决方案：严格规划Hook的职责链（Chain of Responsibility）。将处理原始数据的Hook（如校验、脱敏、格式化）定义为“预处理Hook”，将处理后续状态的Hook（如日志、监控、通知）定义为“后处理Hook”。在代码中明确分组并按顺序注册。更好的做法是设计一个HookManager，它内部维护预处理和后处理两个列表，确保执行顺序符合预期。

class HookManager: def __init__(self): self.pre_hooks = [] # 输入校验、脱敏等 self.post_hooks = [] # 日志、监控等 def register_pre_hook(self, hook): self.pre_hooks.append(hook) def register_post_hook(self, hook): self.post_hooks.append(hook) async def run_pre_hooks(self, event, data): for hook in self.pre_hooks: data = await hook.process(event, data) # 每个hook处理并返回可能被修改的数据 return data async def run_post_hooks(self, event, data): for hook in self.post_hooks: await hook.process(event, data) # 后处理hook通常不修改数据，只观察

4.2 流式输出下的上下文丢失与中断处理

问题描述：在流式传输过程中，如果网络不稳定导致连接中断，用户重连后，Agent可能已经执行了部分操作，但前端只收到了中断前的部分流。简单的重连会导致Agent重新开始执行整个任务，造成重复操作（如重复发送邮件）或状态不一致。

解决方案：实现有状态的会话和断点续传。

1. 会话ID：每个用户请求分配唯一会话ID（Session ID）。
2. 状态持久化：在服务端，将Agent的执行状态（如已完成的步骤、工具调用结果、当前的思维链）与会话ID关联并持久化（存入Redis或数据库）。状态应在每个关键Hook（如on_tool_end,on_llm_end）处更新。
3. 断点续传：当带有相同会话ID的新连接建立时，首先检查是否存在未完成的会话状态。如果存在，则不是重新运行Agent，而是：
   • 将已保存的状态恢复给Agent实例。
   • 向前端首先发送一个session_resume事件，并附带已完成的步骤摘要。
   • 从上次中断的点继续执行流式输出。
4. 超时清理：为每个会话状态设置TTL（生存时间），长时间未恢复的会话自动清理，释放资源。

4.3 总结生成的质量与成本控制

问题描述：直接使用强大的主模型（如GPT-4）来生成总结，效果虽好，但成本高昂，且增加了整体响应延迟。

解决方案：采用分级总结和缓存策略。

• 分级总结：
  • 快速模板总结：对于简单、模式固定的任务（如“查询天气”），直接使用预定义的模板生成总结，毫秒级响应。
  • 轻量模型总结：对于中等复杂度的任务，使用更便宜、更快的模型（如GPT-3.5-Turbo、Claude Haiku）来生成总结。实践发现，对于总结性任务，这些模型在大多数情况下效果足够好。
  • 主模型精炼总结：仅当轻量模型总结的质量评估（可以通过另一个小模型或规则打分）低于阈值时，才动用主模型进行精炼。这构成了一个成本和质量的自适应平衡。
• 缓存策略：对于相同或高度相似的Agent执行轨迹，其总结结果很可能相同。可以对执行轨迹的哈希值进行缓存，在一定时间内（如1小时）直接返回缓存过的总结，显著降低LLM调用成本和延迟。

4.4 Agent失控与安全边界

问题描述：Agent在复杂推理中可能陷入循环，或试图调用不被允许的工具。

解决方案：通过Hook实施“硬性”安全护栏。

• 最大迭代次数限制：在Agent执行循环外设置硬性计数器，超过最大步数（如20步）立即强制终止，并触发总结流程，返回已完成的局部工作。
• 工具调用白名单：在on_tool_startHook中，不仅检查参数，更检查工具本身是否在当前会话的许可范围内。可以根据用户身份、会话上下文动态决定可用的工具集。
• 输出内容过滤：在on_llm_endHook中，对模型生成的最终答案进行强制性的内容安全过滤（使用关键词、正则表达式或调用专门的内容安全API），确保输出符合规范。

性能优化清单：

构建一个成熟的Agent系统，就像组装一台精密的仪器。Hook是它的传感器和控制器，让你能感知和干预内部过程；控制逻辑是它的方向盘和刹车，确保它在正确的轨道上运行；流式输出是它的仪表盘，让用户实时了解进展；而总结则是它的任务报告，将复杂的过程转化为清晰的价值。这四者相辅相成，共同将一个单纯的大语言模型调用，升级为一个可靠、可控、用户体验良好的智能体服务。在实际开发中，没有银弹，需要根据具体的业务场景、风险承受能力和用户体验要求，在这四个维度上找到合适的平衡点。我的经验是，先从最影响当前业务的痛点入手，比如先实现流式输出改善体验，再逐步加入Hook增强可控性，一步步迭代，最终构建出符合自己需求的强大Agent。