1. 项目概述：从“会答题的模型”到“能做事的代理”，我的第一个AI Agent实操手记

你有没有试过让大模型帮你订一杯咖啡？不是让它描述“一杯拿铁的制作流程”，而是真的打开手机App、选门店、加糖减冰、完成支付——它做不到。因为标准的大语言模型（LLM）本质是个“超级文本预测器”：它擅长理解上下文、生成连贯文字、推理逻辑链条，但它没有手脚，不能点击按钮，无法调用天气API，也不能查你的日历空闲时段。而AI Agent，就是给这个“聪明但静止”的大脑，装上眼睛、耳朵和手。它能主动拆解目标（比如“帮我安排下周二下午的团队头脑风暴”），判断当前缺什么信息（查日历？问同事偏好？搜会议室？），调用工具补全信息，再基于新信息继续下一步动作——整个过程不是单次问答，而是一轮接一轮的“思考-决策-行动-观察”循环。这正是ReAct范式的核心：Reason（推理）+ Act（执行）。我第一次跑通这个流程时，用的不是AutoGPT那种需要配置Docker、管理记忆向量库的重型方案，而是一段不到50行的Python代码，依赖LangChain封装好的AgentExecutor和OpenAI的gpt-3.5-turbo。它能实时查询当前时间、搜索网络百科、做简单数学计算，甚至把结果格式化成带emoji的待办清单发给你。这篇文章，就是我把这个“最小可行Agent”从零搭起、踩坑、调优、最终稳定运行的全过程复盘。它不追求炫技，但每一步都经得起拷问：为什么选这个工具链？为什么参数设为这个值？为什么这里必须加个重试机制？如果你刚学完LangChain基础API、对Agent概念还停留在“听起来很酷”的阶段，或者正卡在“写完代码但agent死活不调用工具”的调试瓶颈里，这篇就是为你写的。它不讲虚的架构图，只讲终端里敲下的每一行命令、日志里跳出来的每一个报错、以及我盯着屏幕改了七遍才让agent乖乖去查维基百科的那个下午。

2. 核心设计思路与技术选型解析

2.1 为什么是LangChain + OpenAI？而不是自己造轮子或换框架？

很多人看到“构建AI Agent”第一反应是：“是不是得用Llama.cpp部署本地模型？或者上HuggingFace的Transformers手写推理循环？”——这完全没必要，至少在起步阶段。我的选择逻辑非常务实： 验证核心范式可行性，而非比拼技术栈深度 。LangChain的价值，不在于它多“高级”，而在于它把Agent开发中那些重复、易错、且与业务无关的脏活，打包成了可插拔的模块。比如，一个Agent要工作，至少得解决四个问题：如何把用户指令拆解成可执行步骤（Planning）？如何决定该调用哪个工具（Tool Selection）？如何把工具返回的结果喂回模型继续推理（Observation Injection）？如何防止模型陷入无限循环或胡言乱语（Output Parsing & Safety）？如果自己从头实现，光是写一个鲁棒的tool calling parser，就可能花掉两天时间调试JSON Schema校验失败的边界case。而LangChain的AgentExecutor，已经把这些逻辑封装进 run() 方法里。你只需要专注两件事：定义好你的工具集（Tools），和写好提示词模板（Prompt Template）。至于OpenAI的gpt-3.5-turbo，它的选择更是基于实测数据。我对比过gpt-4、Claude-2和本地部署的Qwen-7B在相同prompt下的tool calling成功率：gpt-3.5-turbo在简单工具链（<5个工具）下稳定在92%以上，而Qwen-7B即使经过微调也仅68%，且响应延迟高3倍。这不是说开源模型不行，而是对于“第一个Agent”这种验证性项目，稳定性压倒一切。你总不想在演示时，agent突然把“搜索Python安装教程”理解成“搜索Python之父的生平”，然后调用维基百科工具返回一堆无关内容吧？所以，我的技术栈就是最精简的黄金组合：LangChain（v0.1.16，注意不是最新v0.2.x，因为v0.1.x的API更直观，文档更全） + OpenAI Python SDK（v1.12.0） + Python 3.10。所有依赖加起来只有3个包， pip install langchain openai python-dotenv 一条命令搞定，省下的时间，全用来调试prompt和观察agent行为模式。

2.2 ReAct范式：不是魔法，而是可拆解的工程逻辑

网上很多文章把ReAct（Reasoning + Acting）说得神乎其神，仿佛是什么黑科技。其实拆开看，它就是一个极其清晰的四步循环协议，LangChain的AgentExecutor就是严格按这个协议执行的。我们来用一个真实例子走一遍：当用户输入“告诉我上海今天的最高气温，然后算出如果降温10度会是多少”。Agent内部发生了什么？第一步， Reason ：模型读取输入，结合自身知识（上海是城市，气温是气象数据），推理出“需要获取实时气温数据”，并意识到“当前没有这个数据，必须调用外部工具”。第二步， Act ：模型严格按照LangChain定义的JSON格式输出一个tool call指令，比如 {"action": "search_weather", "action_input": "Shanghai"} 。注意，这里不是自由发挥，而是被prompt里的few-shot example和output parser死死约束住的。第三步， Observe ：AgentExecutor截获这个JSON，解析出tool name和input，调用你注册的 search_weather 函数，拿到返回值（比如 {"temp_max": 28.5, "unit": "Celsius"} ），再把这个结果原样塞回prompt的“Observation”字段。第四步， Reason again ：模型再次阅读整个上下文——包括原始问题、自己的上一步action、以及刚拿到的observation——然后推理出“现在有了最高温28.5℃，降温10度就是18.5℃”，最后输出最终答案。这个循环可以持续多轮，但每一轮都严格遵循“想→做→看→再想”的节奏。我之所以强调这个细节，是因为几乎所有新手的第一个bug，都出在“Observation”环节：要么忘了在prompt里预留 {observation} 占位符，要么工具返回的数据格式和prompt里要求的不一致（比如prompt写的是 {"temp": 28.5} ，工具却返回了 {"temperature": 28.5} ），导致模型根本看不懂。所以，设计之初我就定下铁律：每个工具的输入输出Schema，必须和prompt中的few-shot example完全镜像。这看起来笨，但能避免80%的调试时间。

2.3 工具集设计：少而精，直击痛点

一个常见的误区是，一上来就想塞满工具：天气、股票、日历、邮件、数据库……结果agent在五六个工具间反复横跳，永远完不成任务。我的策略是“三工具原则”：只保留最能体现Agent价值、且调用逻辑最简单的三个。第一个是 TimeTool ：返回当前UTC时间、时区、星期几。为什么放第一个？因为时间是绝大多数任务的隐含前提。用户说“查今天新闻”，agent必须先知道“今天”是哪天；说“提醒我30分钟后开会”，agent得先确认当前时间才能计算截止点。这个工具零外部依赖，纯Python datetime ，100%可靠，是建立信任感的基石。第二个是 WikipediaTool ：用 wikipedia-api 库搜索词条摘要。选维基不是因为它多权威，而是因为它的API极简——一行代码就能拿到结构化文本，且搜索失败时返回明确的 PageError 异常，方便我们统一处理。第三个是 CalculatorTool ：一个封装了 numexpr 库的计算器。别小看它，这是检验agent“推理链完整性”的试金石。当用户问“北京人口除以上海面积是多少”，agent必须先调用维基查北京人口（比如2154万），再调用维基查上海面积（比如6340平方公里），最后调用计算器算出结果。如果它漏掉中间任何一步，或者把两个数字直接拼成字符串相除，就说明prompt的推理引导没到位。这三个工具加起来，代码不到30行，但覆盖了“获取实时信息”、“检索静态知识”、“执行确定性计算”三大核心能力。后续扩展，比如加一个 SearchTool （用SerpAPI），也是等这三件套跑稳之后的事。记住，Agent的威力不在于工具数量，而在于它能否像人一样，把多个简单工具串成一条解决问题的流水线。

3. 实操搭建：从环境配置到可运行Agent的完整流程

3.1 环境准备与依赖安装：避开版本陷阱

别跳过这一步。LangChain的版本兼容性是出了名的“脆弱”，尤其是v0.1.x和v0.2.x之间API断层极大。我踩过的最深的坑，是某次 pip install langchain 自动装了v0.2.0，结果 from langchain.agents import initialize_agent, Tool 这行代码直接报 ImportError ——因为v0.2.x里 initialize_agent 被移到了 langchain.agents.agent_types ，而旧文档全失效了。所以，我的环境初始化脚本是这样的：

# 创建干净虚拟环境（强烈推荐，避免全局污染）
python -m venv agent_env
source agent_env/bin/activate  # Linux/Mac
# agent_env\Scripts\activate  # Windows

# 指定安装已验证的稳定版本
pip install "langchain==0.1.16" "openai==1.12.0" "python-dotenv==1.0.0" "wikipedia-api==0.6.4" "numexpr==2.8.4"

关键点有三个：第一，必须用 == 锁定版本号，不能用 >= ；第二， python-dotenv 用于安全地管理OpenAI API Key，避免硬编码；第三， wikipedia-api 和 numexpr 是工具依赖，必须提前装好。装完后，立刻验证：

# test_deps.py
import langchain, openai, wikipedia, numexpr
print(f"LangChain: {langchain.__version__}")
print(f"OpenAI: {openai.__version__}")

如果报错，立刻停手，不要往下走。我见过太多人在这里卡住，然后怀疑是API Key错了，其实是 wikipedia 库没装对。另外，OpenAI Key的管理，我坚持用 .env 文件：

# .env 文件内容
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

然后在Python里这样加载：

from dotenv import load_dotenv
load_dotenv()  # 自动读取同目录下的.env文件

这样做有两个好处：一是Git提交时可以放心把 .env 加到 .gitignore ，不怕密钥泄露；二是切换不同环境（开发/测试）只需换一个 .env 文件，不用改代码。这个习惯，从第一天写Agent就要养成。

3.2 工具（Tools）的编写与注册：让Agent“看得见”你的能力

工具不是随便写个函数就行，它必须符合LangChain的 Tool 类契约。核心是三个属性： name （工具名，必须唯一且简洁）、 description （功能描述，这是agent做tool selection的唯一依据）、 func （执行函数，必须是同步的，且返回str）。我们以 TimeTool 为例：

from datetime import datetime, timezone
from langchain.tools import Tool

def get_current_time() -> str:
    """Returns current UTC time, timezone, and weekday in a human-readable format."""
    now = datetime.now(timezone.utc)
    # 格式化：2023-11-05 14:30:22 UTC, Sunday
    return now.strftime("%Y-%m-%d %H:%M:%S %Z, %A")

time_tool = Tool(
    name="time",
    description="Useful for when you need to know the current time and date. Input is always empty.",
    func=get_current_time
)

注意 description 里的细节：“Useful for when you need to know...” 这是告诉agent这个工具的适用场景；“Input is always empty.” 这是关键！因为 get_current_time 不需要任何参数，如果description里没写清楚，agent可能会瞎猜一个输入（比如“now”），导致调用失败。再看 WikipediaTool ，它需要搜索词，所以description必须明确输入格式：

import wikipedia

def search_wikipedia(query: str) -> str:
    """Search Wikipedia for a given query and return the first paragraph of the summary."""
    try:
        page = wikipedia.page(query, auto_suggest=False)
        # 只取前200字，避免observation过长干扰模型
        return page.summary[:200] + "..."
    except wikipedia.DisambiguationError as e:
        return f"Multiple results found: {', '.join(e.options[:3])}. Please be more specific."
    except wikipedia.PageError:
        return f"No Wikipedia page found for '{query}'. Try a different term."

wiki_tool = Tool(
    name="wikipedia",
    description="Useful for when you need to look up factual information from Wikipedia. Input is the search term.",
    func=search_wikipedia
)

这里有两个经验：第一， auto_suggest=False 关闭自动纠错，避免搜“Python”却返回“Monty Python”的尴尬；第二， summary[:200] 强制截断，因为LangChain的默认prompt对observation长度有限制，超长会导致模型忽略关键信息。最后是 CalculatorTool ，它展示了如何处理复杂输入：

import numexpr as ne

def calculate(expression: str) -> str:
    """Evaluate a mathematical expression. Supports +, -, *, /, **, and parentheses."""
    try:
        # 安全过滤：只允许数字、基本运算符和括号
        if not all(c in "0123456789+-*/(). " for c in expression):
            return "Invalid characters in expression. Only numbers, +, -, *, /, **, (, ), and spaces are allowed."
        result = ne.evaluate(expression).item()
        # 处理浮点数精度，避免显示1.2345678901234567e-05这种
        if isinstance(result, float) and result.is_integer():
            return str(int(result))
        return f"{result:.6g}"  # 自动选择合适精度
    except Exception as e:
        return f"Calculation error: {str(e)}"

calc_tool = Tool(
    name="calculator",
    description="Useful for when you need to perform mathematical calculations. Input is a valid arithmetic expression, e.g., '2 + 2' or '(10 * 5) / 2'.",
    func=calculate
)

numexpr 比 eval() 安全得多，且支持向量化运算。 description 里的例子 '2 + 2' ，就是给agent的few-shot示范，它会模仿这个格式生成自己的action_input。所有工具写完后，用一个列表注册：

tools = [time_tool, wiki_tool, calc_tool]

这就是agent能“看见”的全部世界。它不会凭空发明新工具，只会在这三个里挑。

3.3 Prompt工程：用“思维链”引导Agent的每一步推理

LangChain的AgentExecutor默认用 ZeroShotAgent ，它的prompt是动态生成的。但默认prompt太“通用”，容易让agent在简单任务上过度思考。我的做法是，完全自定义一个 PromptTemplate ，用最少的token，灌输最关键的思维指令。核心是三段式结构：

from langchain.prompts import PromptTemplate

# Few-shot examples：必须真实、简短、覆盖典型case
examples = [
    # Case 1: 纯时间查询
    """Question: What time is it?
Thought: I need to know the current time.
Action: time
Action Input: 
Observation: 2023-11-05 14:30:22 UTC, Sunday
Thought: I have the current time.
Final Answer: It is 14:30:22 UTC on Sunday, November 5th, 2023.""",
    
    # Case 2: 维基搜索+简单计算
    """Question: How many people live in Tokyo?
Thought: I need to look up Tokyo's population on Wikipedia.
Action: wikipedia
Action Input: Tokyo
Observation: Tokyo is the capital city of Japan. As of 2020, the Greater Tokyo Area had a population of approximately 37.4 million...
Thought: The population is approximately 37.4 million.
Final Answer: Approximately 37.4 million people live in the Greater Tokyo Area."""
]

# 主Prompt模板
template = """Answer the following questions as best you can. You have access to the following tools:

{tools}

Use the following format:

Question: the input question you must answer
Thought: you should always think like you are answering the question step by step
Action: the action to take, should be one of [{tool_names}]
Action Input: the input to the action
Observation: the result of the action
... (this Thought/Action/Action Input/Observation can repeat N times)
Thought: I now know the final answer.
Final Answer: the final answer to the original input question

Begin! Remember to give your Final Answer in clear, concise language.

{examples}

Question: {input}
Thought:"""

prompt = PromptTemplate(
    template=template,
    input_variables=["input", "tools", "tool_names", "examples"],
    partial_variables={"examples": "\n\n".join(examples)}
)

这个prompt的设计哲学是“少即是多”。首先， examples 只放两个，且都是成功案例，绝不放错误示例（那会教坏agent）。其次， Thought 的引导语是“you should always think like you are answering the question step by step”，这比默认的“you should think about what to do next”更强调分解步骤。最关键的是 Final Answer 的指令：“in clear, concise language”，这直接压制了模型爱写长篇大论的毛病。我测试过，不加这句，agent回答“上海气温”时会输出一段200字的气象学科普；加了之后，它老老实实只说“28.5°C”。最后， partial_variables 把examples固化进prompt，避免每次run都重新拼接，提升稳定性。这个prompt，就是agent的“操作手册”，它决定了agent是像个严谨工程师，还是个啰嗦哲学家。

3.4 AgentExecutor初始化与运行：让“思考”真正落地

万事俱备，只欠执行。LangChain的 AgentExecutor 是真正的“指挥官”，它把prompt、tools、LLM三者拧成一股绳。初始化代码如下：

from langchain.chat_models import ChatOpenAI
from langchain.agents import AgentExecutor, ZeroShotAgent

# 初始化大模型（注意：必须用ChatOpenAI，不是OpenAI）
llm = ChatOpenAI(
    model_name="gpt-3.5-turbo",  # 不是text-davinci-003！
    temperature=0,  # 0意味着确定性输出，避免随机性干扰调试
    max_tokens=512,  # 防止response过长
    verbose=True  # 关键！开启verbose，能看到每一步的prompt和response
)

# 创建agent
agent = ZeroShotAgent.from_llm_and_tools(
    llm=llm,
    tools=tools,
    prompt=prompt,
    # 这个参数至关重要：它告诉agent，当tool call失败时，不要崩溃，而是返回错误信息给模型继续推理
    handle_parsing_errors="Check your output and make sure it conforms! Action: ... Action Input: ..."
)

# 执行器
agent_executor = AgentExecutor.from_agent_and_tools(
    agent=agent,
    tools=tools,
    verbose=True,  # 再次开启，看到tool调用详情
    # 最大迭代次数：防止死循环。3次足够处理95%的简单任务
    max_iterations=3,
    # 如果超过max_iterations，返回这个兜底消息
    early_stopping_method="generate"
)

# 运行！
result = agent_executor.run("What is the population of Paris?")
print(result)

这段代码里，有三个极易被忽略的细节。第一， model_name 必须是 "gpt-3.5-turbo" ，且必须用 ChatOpenAI 类。 OpenAI 类是为completion API设计的，不支持chat message格式，会导致tool calling完全失效。第二， temperature=0 不是为了“更准”，而是为了“可复现”。调试时，你必须确保同样的输入，永远得到同样的中间步骤，否则无法定位是prompt问题还是模型随机性问题。第三， handle_parsing_errors 参数是救命稻草。当agent输出的JSON格式错误（比如少了个逗号），默认行为是抛异常中断。而设成字符串后，它会把错误信息作为Observation喂回模型，模型看到 "Check your output..." ，就会自我纠正，重新输出合法JSON。我亲眼见过agent连续7次格式错误后，在第8次完美调用工具——这就是容错机制的价值。运行时， verbose=True 会打印出完整的prompt和模型response，这是你理解agent“怎么想”的唯一窗口。比如，你会看到它把“巴黎人口”拆解成 Thought: I need to search Wikipedia for Paris population ，然后输出 Action: wikipedia ，再看到 Observation: Paris is the capital... population of 2.1 million ，最后 Final Answer: 2.1 million 。这个trace，就是你优化prompt的全部依据。

4. 常见问题与实战排错技巧：那些文档里不会写的坑

4.1 “Agent死活不调用工具”：九成是Prompt描述惹的祸

这是新手遇到的第一座大山。你明明注册了 time_tool ，输入“现在几点”，agent却直接回答“我不知道，我需要调用工具”，然后就卡住了。根本原因，几乎100%出在 Tool.description 。LangChain的tool selection，本质是一个文本匹配过程：模型把用户问题和所有tool的description做语义相似度计算，选分最高的那个。所以，description必须像搜索引擎关键词一样精准。反面案例： "Get time info" ——太模糊，模型不知道“info”指什么。正面案例： "Useful for when you need to know the current time and date. Input is always empty." ——包含了触发场景（need to know current time）、输入特征（always empty），还暗示了工具名（time）。我做过一个实验：把description改成 "Returns the current time in UTC." ，调用成功率从45%飙升到92%。为什么？因为“current time”和用户问题里的“现在几点”完全匹配。另一个致命错误是description里用了缩写。比如 "Get curr time" ，模型可能根本不懂 curr 是 current 的缩写。所以，我的tool description黄金法则是：用完整单词，包含用户可能问的关键词，明确输入输出约束。写完description，一定要用 print(agent.llm_chain.prompt.format_prompt(...)) 打印出最终prompt，人工检查description是否被正确注入。

4.2 “Observation太长，Agent看不懂”：截断与摘要的艺术

维基百科一页摘要动辄上千字，而LangChain的默认prompt只给Observation留了200-300 token空间。当observation溢出，模型会直接忽略后面的内容，导致“查到了但没看见”。解决方案不是加长context window（那会增加成本和延迟），而是前端截断+后端摘要。我的实践是双保险：第一，在tool函数里强制 summary[:200] ；第二，在prompt的few-shot example里，刻意展示一个被截断的observation，比如 Observation: Tokyo is the capital... (truncated) ，这样模型就学会了“看到(truncated)就明白信息不全，需要追问”。更高级的技巧是用LLM做摘要，但这对第一个Agent来说是杀鸡用牛刀。我试过用gpt-3.5-turbo本身摘要维基内容，结果发现它摘要后的信息，还不如原文前200字准确——因为摘要过程又引入了一次幻觉风险。所以，最朴实的 [:200] ，反而是最可靠的。

4.3 “Agent陷入无限循环”：用max_iterations和thought监控双保险

当agent在 Thought: I need to search Wikipedia for X 和 Observation: No page found for X 之间反复横跳，就是典型的死循环。根因是模型没学会“失败即终止”。解决方案有二：第一， max_iterations=3 是底线，绝不能设为 None ；第二，在prompt的few-shot example里，必须包含一个“失败处理”的案例。我新增了一个example：

"""Question: What is the population of Zztopia?
Thought: I need to look up Zztopia's population on Wikipedia.
Action: wikipedia
Action Input: Zztopia
Observation: No Wikipedia page found for 'Zztopia'. Try a different term.
Thought: Wikipedia has no information about Zztopia. It may not exist or be misspelled.
Final Answer: I couldn't find any information about 'Zztopia' on Wikipedia. It might not be a real place or could be spelled differently."""

这个example教会agent三件事：1）遇到 No page found 要识别为失败信号；2）失败后不要重试，而是分析原因；3）最终答案要诚实告知用户。同时，我在代码里加了thought日志监控：

import re
# 在agent_executor.run后，检查thought是否重复
thoughts = re.findall(r'Thought: (.*?)(?:\n|$)', agent_executor.memory.buffer)
if len(thoughts) > 2 and thoughts[-1] == thoughts[-2]:
    print("Warning: Thought repeated! Possible loop detected.")

这种简单粗暴的字符串匹配，比任何复杂算法都管用。

4.4 “工具调用失败，但没报错”：异常捕获与用户友好的错误传递

wikipedia-api 的 PageError 异常，如果不在tool函数里捕获，就会炸穿AgentExecutor，返回一长串stack trace给用户。这体验极差。正确做法是在每个tool的 func 里，用 try...except 兜住所有异常，并返回一个 用户能懂的、agent能处理的字符串 。比如：

def search_wikipedia(query: str) -> str:
    try:
        # ... 正常逻辑
    except wikipedia.DisambiguationError as e:
        return f"Multiple results found: {', '.join(e.options[:3])}. Please be more specific."
    except wikipedia.PageError:
        return f"No Wikipedia page found for '{query}'. Try a different term."
    except Exception as e:
        return f"Search failed due to an unexpected error: {str(e)}. Please try again later."

注意，每个return都是自然语言，不是JSON或error code。因为agent的“大脑”只能处理文本，它看到 "No Wikipedia page found..." ，就能理解这是搜索失败，进而调整后续Thought。如果返回 {"error": "PageNotFound"} ，agent大概率会懵圈。这个原则适用于所有工具：计算器的 Invalid characters ，时间工具的 Network timeout ，都要翻译成agent和用户都能懂的话。

4.5 性能与成本：如何让Agent又快又省

gpt-3.5-turbo按token计费，而Agent的每一次Thought/Action/Observation循环，都在消耗token。一个看似简单的“查上海气温”，可能经历：1）初始prompt（含tools description）约300 token；2）Thought + Action + Input约50 token；3）Observation（天气API返回）约100 token；4）Final Answer约30 token。总计近500 token。如果用户连续问5个问题，就是2500 token，成本虽小，但积少成多。我的优化策略是“缓存+精简”。第一，对 time_tool 这种结果不变的工具，加内存缓存：

from functools import lru_cache

@lru_cache(maxsize=1)
def get_current_time() -> str:
    # ... same as before

这样，只要进程不重启， time 工具永远只调用一次。第二，精简prompt：删掉所有冗余空格和换行，把examples压缩到最简。我曾把prompt从800 token压到450 token，响应速度提升40%，成本减半。第三， max_tokens=512 是硬性限制，防止模型在Final Answer里写小作文。这些细节，文档从不提，但它们决定了你的Agent是能上线的产品，还是只能本地演示的玩具。

5. 进阶思考与个人实践心得：从能用到好用的跨越

跑通第一个Agent只是起点。在我把它部署到公司内部Slack机器人、服务了200+同事一个月后，一些更深层的认知浮现出来。最大的体会是： Agent的“智能”，70%来自工具设计，20%来自prompt工程，只有10%来自LLM本身 。什么意思？当你把 wikipedia 换成一个能返回结构化JSON的内部知识库API，agent瞬间就能回答“我们Q3销售目标达成率是多少”；当你把 calculator 换成一个能连接数据库执行SQL的 DBQueryTool ，agent就能回答“上个月华东区客单价Top 5的客户是谁”。LLM只是那个读懂指令、串联步骤的“调度员”，真正的“肌肉”和“感官”，是你赋予它的工具。所以，我现在的开发重心，已经从“怎么让gpt-3.5-turbo更好用”，转向了“怎么设计一个更鲁棒、更易集成、返回更干净数据的工具”。

另一个血泪教训是关于“可控性”。早期我迷信LLM的泛化能力，给了agent一个 SendEmailTool ，结果它在测试时真的给CEO发了一封主题为“Test Email from AI Agent”的邮件。虽然内容无害，但足以让IT部门找上门。从此我立下铁规：所有具备“副作用”的工具（发邮件、改数据库、调用支付API），必须加一层人工审批开关，且默认关闭。在tool function里，第一行就是 if not os.getenv("EMAIL_ENABLED"): return "Email tool is disabled. Contact admin to enable." 。安全不是feature，是baseline。

最后，关于评估。别信“准确率95%”这种虚数。我用的真实评估法，叫“10分钟压力测试”：随机选10个真实用户问题（从历史客服工单里扒），让agent逐个回答，记录三个指标：1）是否调用正确工具（如问时间，是否调 time ）；2）是否在max_iterations内给出答案；3）Final Answer是否解决了用户原始需求（不是语法正确，而是实质有效）。比如用户问“帮我取消明天上午10点的Zoom会议”，agent调了 calendar 工具但返回“会议不存在”，这不算成功，因为没帮用户解决问题。这个测试，我每周做一次，数据曲线比任何benchmark都真实。它告诉我，不是模型不够强，而是我的 calendar 工具缺少“模糊匹配会议标题”的能力——这才是下一步该优化的地方。

这个项目没有终点。昨天，我把 WikipediaTool 替换成了公司Confluence的搜索API，今天，我在写一个能解析PDF合同、提取关键条款的 ContractParserTool 。Agent的进化，从来不是靠换更大的模型，而是靠给它装上更趁手的工具，和更清晰的指令。当你亲手把第一个 time 工具跑通，看着终端里跳出“2023-11-05 14:30:22 UTC, Sunday”时，你就已经站在了AI应用开发的新大陆上。剩下的，只是不断打磨你的工具箱而已。