AI Agent实战：从零构建一个会调用工具的智能体

我见过不少朋友第一次接触 AI Agent 时的状态：看到各种宣传视频里 Agent 自动查资料、写代码、订机票，觉得这东西太神奇了，恨不得马上动手复刻一个。结果真到上手的时候，要么被各种概念绕晕，要么照着教程抄了一个 demo，跑通了却不知道怎么改造成自己的东西。这篇文章就是为了解决"从 0 到 1"这个过程里的真实问题而写的。

我会用一次完整的实战项目作为主线，从任务拆解、技术选型，到核心代码实现、工具调用细节，再到记忆管理和部署测试，把构建一个 AI Agent 的完整路径走一遍。内容尽量说得通俗，但不会回避底层原理。只要你写过一点 Python，哪怕对 AI 的理解还停留在"调 API"的阶段，也能跟着这篇文章做出一个真正能跑、能用的 Agent 出来。更重要的是，你会理解每一步为什么要这么做，而不是盲目照搬。

先说明一下：这篇文章里的例子是一个"个人知识库问答 Agent"，它能根据你指定的本地文档回答问题，并且会自动调用搜索引擎补全文档里没有的信息。这个任务不大不小，恰好能覆盖 Agent 开发最核心的几个环节：意图规划、工具调用、记忆管理和多轮对话。把它吃透，其他复杂项目基本就是往这个骨架上加东西。

1. 先别急着写代码:搞清楚你的 Agent 到底要解决什么问题

很多人做 Agent 项目翻车，不是代码写错了，而是压根没想清楚任务边界。Agent 不是什么都能干的万能程序，它本质上是"大语言模型 + 工具 + 执行循环"的组合体。在动手之前，有两件事必须想明白。

1.1 普通函数和 AI Agent 的本质差异

传统程序是一套固定的流程：输入进来，走判断分支，调函数，输出结果。它的优点是确定性强，同样的输入永远得到同样的输出。缺点也很明显——一旦遇到规则覆盖不到的情况，程序就死了。

AI Agent 不一样。它靠语言模型驱动，核心不是流程，而是"决策"。模型的输出是一个个动作选择：要不要调用搜索工具、要用哪个参数、找到了信息之后下一步做什么。你写代码的时候，重点不是在实现某一个固定流程，而是在"定义模型可以使用的动作空间，以及每个动作的边界"。模型负责规划，代码负责兜底。

打个比方：传统程序是你在超市照着购物清单买东西，每一步都是规定好的；Agent 是派了一个会说人话的助理去超市，他手里有个清单，但遇到缺货商品可以自己决定换个品牌、问店员库存、或者打电话回来请示。你要做的是给他交代清楚"什么情况可以换、什么情况必须问"，而不是替他把每一步都走完。

1.2 什么样的任务适合 Agent，什么样的不适合

不适合 Agent 的任务有几个特征：

• 对时效性和准确性要求极高，比如金融交易、医疗诊断。模型的一次幻觉可能带来不可逆损失。
• 执行步骤完全固定，没有决策空间。直接写个脚本更快、更省、更稳。
• 需要严格的权限隔离和审计，Agent 的自由发挥反而制造风险。

适合 Agent 的任务恰好反过来：任务边界模糊、需要多步推理、需要调用多种外部工具、允许在有限范围内试错。比如：根据内部文档回答员工问题、整理统一格式的市场调研报告、自动对邮件分类并起草回复草稿。

我这次选"个人知识库问答 + 联网补全"，就是因为它的边界足够清晰——只处理两个信息源（本地文档、搜索引擎），所有操作可审计、可撤销，非常适合作为入门项目。

提示：不要把 Agent 的第一步项目设计得过于"全能"。一个需要对接十几个系统、处理多种权限、涉及多用户并发的大型 Agent，对刚入门的开发者来说难度是灾难级的。先用单用户、单数据源、少工具的项目建立信心，再一步步加复杂度。

2. 技术选型与架构设计:模型、框架、还有四个核心模块

这个环节最容易被忽视，但恰恰决定了项目的天花板。选型不是"哪个火选哪个"，而要回到你的任务需求来倒推。

2.1 模型选择与接口约定

字生成能力、长上下文理解能力、工具调用（function calling）能力。

工具调用能力是 Agent 项目的硬性指标。模型需要能从对话内容中识别出"用户想让我搜索一下"，并且输出结构化的调用参数，而不是自然语言描述。如果选一个不支持工具调用的模型，Agent 项目也能做，但解析输出会非常痛苦，基本等于"让模型写纸条，你再去念纸条执行"，多了一层脆弱性。

我的建议：第一次做 Agent 项目，直接选择支持 function calling 的模型，接口遵循 OpenAI 风格即可。国内可用的模型服务大多兼容 OpenAI 的接口格式，这样你的代码可以无缝切换不同模型商，不会被某一家锁死。

2.2 框架选择:全自主 Agent 的问题

市面上有不少 Agent 框架，比如 AutoGPT 这类代表"全自主"想法的产品。它们宣传得很诱人：你给它一个目标，它自己拆解、自己执行、自己反思。但实际用下来，全自主 Agent 有两个严重问题：

第一个是失控。Agent 一旦进入长任务循环，模型可能逐渐偏离原始目标，开始做各种无关操作，你甚至说不清楚它在哪一步跑偏的。第二个是成本失控。全自主循环意味着大量 token 消耗，一个本可以用 10 次调用完成的任务，它可能调用上百次，费用和延迟都不可接受。

所以我的建议是：第一次做 Agent，不要用全自主框架，用"半自主 + 人在环路"的模式。也就是说，模型在预定义的步骤内自主决策，但关键节点你需要设置检查点。具体到架构上，就是不依赖某个"一步到位的魔法框架"，而是自己搭建一个轻量的执行循环。

2.3 最小化架构:规划、工具、记忆、执行

一个 Agent 项目不管多复杂，最后都能抽象成四个模块：

这四个模块缺一不可。规划器负责"想"，工具集负责"做"，记忆负责"记住"，执行器负责把三者串起来。我见过很多半成品 Agent，要么有工具没记忆，每次对话都是失忆状态；要么有记忆没有规划，模型只知道聊闲天，不知道调用工具。架构设计阶段把每一块的职责写在纸上，后面写代码才会有方向。

另外要提一个关键设计决策：工具返回的数据格式必须由你定义，而不是由模型定义。模型只负责决定"调哪个工具、传什么参数"，工具返回什么内容，必须是你代码里写死的结构化数据。这样才能保证 Agent 不会因为一次格式飘忽的输出而崩溃。

3. 核心循环的代码实现:让 Agent 真正跑起来

架构设计完了，接下来是实操环节。我会把核心代码一段段拆开讲，每一段代码的目的和关键点都说清楚。这里使用的示例项目名叫"某知识库助手"，它只做三件事：读取本地文档、向量化存储、根据用户问题做检索增强回答，需要时调用搜索工具补全信息。

3.1 工具的定义和注册

先定义工具。我们可以用一个简单的装饰器模式实现工具注册表，这比手写一堆 if-else 要清爽得多。

import json from typing import Callable, Dict, Any # 工具注册表 TOOL_REGISTRY = {} def register_tool(name: str, description: str, parameters: dict): """注册工具，name 唯一，description 和 parameters 会被传给模型用于决策""" def decorator(func: Callable) -> Callable: TOOL_REGISTRY[name] = { "function": func, "description": description, "parameters": parameters, } return func return decorator @register_tool( name="search_knowledge_base", description="在本地知识库中检索与问题相关的文档片段", parameters={ "type": "object", "properties": { "query": {"type": "string", "description": "检索关键词"} }, "required": ["query"] } ) def search_knowledge_base(query: str) -> str: # 这里简化：假设我们有一个检索函数 results = retrieve_similar_chunks(query, top_k=3) return json.dumps(results, ensure_ascii=False) @register_tool( name="search_web", description="当本地知识库无法回答问题时，搜索互联网获取最新信息", parameters={ "type": "object", "properties": { "query": {"type": "string", "description": "搜索关键词"} }, "required": ["query"] } ) def search_web(query: str) -> str: results = web_search_api(query) return json.dumps(results, ensure_ascii=False)

这段代码有两个容易忽略的地方。

第一个是parameters字段。它不是给人看的，是给模型看的。模型会根据description和parameters的 schema 来决定是否调用工具、怎么填参数。如果你的描述含糊，模型就可能填出格式不对的参数；如果 required 漏了字段，模型可能直接不传这个参数。所以每个工具的描述必须写清楚"什么时候调用、不调用会有什么后果"。

第二个是返回格式。我统一把结果转成 JSON 字符串，方便后续模型读取。但实际项目中不能把大段搜索结果全塞给模型，这会造成严重的 token 浪费。正确做法是在工具内部先做一轮信息提取，只返回最核心的内容。

3.2 规划器提示词与主循环

工具注册好了，现在写主循环。核心思路是：每次把用户的原始问题、对话历史、工具定义一起发给模型，让模型决定是直接回答还是调用工具。

from openai import OpenAI client = OpenAI( api_key="YOUR_API_KEY", base_url="YOUR_API_BASE_URL" ) SYSTEM_PROMPT = """你是一个知识库问答助手。请根据用户的问题： 1. 优先调用 search_knowledge_base 检索本地知识库。 2. 如果检索结果无法回答问题，调用 search_web 获取补充信息。 3. 根据检索结果组织回答，并标注信息来源。 你必须一步一步思考，但不要在回答中透露你的推理过程。""" def run_agent(user_query: str, history: list) -> str: messages = [ {"role": "system", "content": SYSTEM_PROMPT}, ] + history + [ {"role": "user", "content": user_query} ] for step in range(MAX_STEPS): response = client.chat.completions.create( model="MODEL_NAME", messages=messages, tools=[tool_schema(t) for t in TOOL_REGISTRY.values()], ) message = response.choices[0].message # 模型没有要求调用工具，说明可以直接回答 if not message.tool_calls: return message.content # 模型要求调用工具，解析参数并执行 for tool_call in message.tool_calls: func_name = tool_call.function.name args = json.loads(tool_call.function.arguments) result = TOOL_REGISTRY[func_name]["function"](**args) messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": result, }) return "运行超时，无法完成任务"

这个循环本身很简洁，但有一个核心设计需要理解：messages的长度会不断增长——每一次工具调用，我们都会追加一条包含工具结果的tool消息。这在技术上没毛病，但 token 消耗也会随之增长。一个复杂任务如果调用 10 次工具，历史消息里就会积累 20 多条内容，很快就会撑爆上下文窗口。

所以实际项目中必须对消息做压缩，具体方案我在后面记忆管理部分细说。

3.3 用 LangChain 还是自己写循环

我在选型阶段特意没提 LangChain，因为对新手来说它是个陷阱。LangChain 封装了很多抽象概念，比如 Chain、Agent、Tool，初次使用会觉得处处是魔法。但问题在于：一旦出了 bug，你根本不知道是它内部哪一层出了问题，排查难度比直接用 openai SDK 写循环高一个量级。

我的建议很简单：

• 第一次做 Agent，直接用openaiSDK + 手写循环，最多 100 行代码就能搞定。
• 等你对整个流程完全理解了，再考虑框架。
• 即使使用框架，也建议优先用偏轻量的方案，不要一上来就全家桶。

自己的代码出 bug 你还有办法调试，框架的 bug 你只能去翻源码，这就是本质区别。

4. 让 Agent 真正会"动手":工具调用的避坑细节

核心循环能跑通，只代表骨架立起来了。真正的魔鬼都在工具调用细节里。这一章我重点说几个常见问题，全部来自实际开发中踩过的坑。

4.1 function calling 的两个诡异场景

第一个诡异场景是"模型明明返回了 tool_calls，但参数是空的"。这通常发生在参数 schema 设计不够严谨的时候。我曾经设计过一个工具，它的参数只要求一个可选字段，结果模型直接返回空参调用，导致后端工具收到空字典直接报错。

解决办法是在执行工具前做一层参数校验，不合法就返回错误信息给模型，让它重新生成：

def safe_call_tool(func, args): try: result = func(**args) except TypeError as e: return f"调用参数错误: {e}，请检查参数后重试" except Exception as e: return f"工具执行异常: {e}" return result

不要假设模型一定会输出合法 JSON。它只是"大概率"输出合法 JSON，你要为那个小概率做好兜底。

第二个诡异场景是"模型编造工具调用结果"。这不是模型故意的，而是模型本身的"补全"特性导致的。如果上下文信息不足，模型可能认为"我应该调用工具了"而不是"我确实调用了工具并收到了结果"，然后一本正经地回答。这种现象在上下文被压缩后特别明显。

解决方案有两个方向：一是在 system prompt 里强调"只有收到工具调用结果时才能引用，否则必须再次调用工具"；二是在代码层面隔绝——只有真实的工具返回结果才能被放入消息列表，模型不可能凭空生成一个tool角色的消息。

4.2 多工具协作时的状态传递

我的知识库助手有两个工具，它们之间没有强依赖，但有些真实场景下，工具之间有调用关系。比如先调用"查询天气API"拿到城市编号，再调用"查询航班"时需要用到这个编号。这种情况下，状态保存在哪？

最直观的做法是把中间状态塞回上下文，让模型在下一次决策时读取。这可行，但风险是模型可能忘记传参。更稳妥的做法是在工具函数内部完成状态传递——你可以在工具函数的返回值里带上一个context字段，然后在下一个工具的代码里直接从某个数据结构读取。

实际项目里我建议：

• 工具之间不要做复杂的隐性依赖。如果必须依赖，优先把两个工具合并成一个复合工具。
• 工具尽量是无状态的，输入什么、输出什么，不依赖前一次调用的副作用。
• 所有工具的输入输出都打印日志，这是排查问题的基础。

4.3 工具返回内容的"token 瘦身"

检索类工具最容易出现的一个问题是：你让工具返回了 10 条文档片段，每条 500 字，模型读一次上下文就消耗 5000 token。如果后续还要多次调用，上下文很快就会爆掉。

所以工具内部一定要做"信息压缩"，我只强调一个原则：工具给模型的不是原始数据，而是经过预处理的答案片段。检索到 10 条相关内容后，工具内部可以用关键词抽取、摘要、或者直接截取与问题最相关的句子，只返回最核心的 3-5 条。这样模型拿到的是"半成品"，而不是"原材料"。

比如搜索工具可以这样优化：

def search_knowledge_base(query: str) -> str: chunks = retrieve_similar_chunks(query, top_k=10) # 压缩：每个片段只保留包含关键词最多的 3 个句子 compact = [] for chunk in chunks: sentences = split_sentences(chunk) ranked = rank_sentences_by_relevance(sentences, query) compact.append(" ".join(ranked[:3])) return json.dumps(compact, ensure_ascii=False)

这一步优化做得好，等于给你的 Agent 免费扩容了上下文窗口，比单纯换一个长上下文模型划算得多。

5. 记忆管理:从一次对话到持续服务

如果一个 Agent 没记忆，每轮对话都是孤立的，用户体验会很差。这里的"记忆"分两个层面：会话级记忆负责多轮对话的连贯性，长期记忆负责跨会话的持久化。两种实现难度完全不同。

5.1 会话记忆与滑动窗口

最简单的会话记忆就是保存对话历史列表，每次请求时把历史一起发给模型。但这里有个问题：历史无限增长，token 消耗无限增多。你需要一套压缩策略。

我常用的方案：

1. 设定一个历史条数阈值，比如 20 条。超过之后，将最早的消息丢弃或摘要化。
2. 每轮对话结束后，让模型生成一个"本轮摘要"，存储到一个单独的变量里。当历史被截断时，把摘要作为高优先级消息保留。
3. 系统消息里始终保留用户的最初意图描述，防止模型在长对话中跑偏。

具体实现上，摘要不必太复杂，一句话就够：

SYSTEM_PROMPT = """当对话历史过长时，你会收到一条 SUMMARY 消息，它是之前对话的摘要。请基于当前问题和摘要继续回答。""" def compress_history(messages: list) -> list: if len(messages) <= MAX_HISTORY: return messages # 取系统消息 + 最新 MAX_HISTORY 条消息 new_messages = [messages[0]] + messages[-MAX_HISTORY:] # 可选：让模型生成本轮摘要 summary = summarize_messages(messages[1:-MAX_HISTORY]) if summary: new_messages.insert(1, {"role": "system", "content": f"历史摘要: {summary}"}) return new_messages

压缩策略的核心思想：不追求保留全部信息，只保留与当前任务最相关的部分。模型本身有强大的理解能力，一句高质量的摘要比 20 条冗余的原始消息更有效。

5.2 长期记忆与向量库选型

跨会话的长期记忆，本质是"把重要的信息存起来，下次需要时再检索出来"。我这次的示例项目用了向量库来存储文档切片，选型上有几个考量：

第一次做项目，我推荐本地向量库。部署简单，数据在本地，调试方便。但要注意：向量库本身不产生向量，你需要调用模型做 embedding。这一步的模型选择和调优直接决定检索质量。

5.3 记忆写入的最佳时机

很多教程会告诉你"对话结束把关键信息存入向量库"，但没告诉你什么时候存、存什么。我的经验是两个时机：

第一个时机是"用户明确表达偏好"的时候。比如用户说"以后回答尽量简洁一点"，这就是一条值得长期记忆的偏好信息。你可以通过一个分类工具识别出这类句子，然后写入长期记忆。

第二个时机是"工具返回了有价值的新信息"的时候。比如搜索工具带回了一条本地知识库没有的信息，你可以把它处理后保存，下次检索就能命中。这就是记忆系统最实用的应用——Agent 的一次探索成果，沉淀为长期资产。

注意别把每轮对话全存进长期记忆。长期记忆存得越多，检索结果里噪声越多，回答质量反而下降。只存高价值信息，这是印象最深的一条实践规则。

6. 测试与部署:Agent 项目最容易翻车的地方

代码写完只是开始，把一个 Agent 项目跑到能稳定服务，才是真正的挑战。这章聊测试策略和部署运维的实际经验。

6.1 单元测试与回归测试怎么设计

Agent 项目有个特点是"非确定性"——同样的输入，模型输出可能每次都不同。传统软件的单元测试思路在这里不完全适用。你不能断言"输入 A 一定输出 B"，因为模型受温度和上下文波动影响。

我的做法是建立三层测试体系：

第一层是工具层测试。每个工具函数是纯代码，输入输出是确定的，可以像传统软件一样测试。这部分测的是逻辑正确性，比如检索函数是否能正确处理空库、搜索 API 参数拼接是否正确。

第二层是工具调用意图测试。给模型一组固定问题，断言它调用了哪个工具、参数结构是否合法。这一步测的是提示词是否写清楚。比如：

def test_web_search_intent(): result = run_agent("帮我搜索一下最新的行业报告") # 断言模型确实调用了 search_web assert "search_web" in get_call_trace(result)

第三层是端到端测试，跑真实场景，只检查回答中是否包含了关键信息，不逐字比对。比如用户问"项目预算是多少"，只要回答里出现预算金额且来源标注正确，就算通过。

6.2 日志追踪:一次性工具调用的可视化

Agent 项目的调试最大痛点是"看不见过程"。API 返回信息、工具中间结果、token 消耗，这些发生在代码内部，普通日志难以快速定位。

我建议从第一天就给关键流程打结构化日志：

import logging logger = logging.getLogger("agent") def log_agent_step(tool_name, args, result, token_cost): logger.info(json.dumps({ "event": "tool_call", "tool": tool_name, "args": args, "result_preview": result[:500], "tokens": token_cost, "timestamp": datetime.now().isoformat(), }, ensure_ascii=False))

然后你可以把日志导入任意日志平台，或者在本地用一个简单的脚本分类统计。工具调用的序列一目了然——模型是先检索再搜索，还是东一榔头西一棒子？每个环节花了多少 token？这些信息对优化提示词和压缩上下文至关重要。

另一个实践经验：给每次对话生成一个唯一的 trace_id，日志贯穿全局。排查问题时，你只需要搜索这一个 ID，就能拿到完整的调用链路。没有这一步，Agent 出问题时你基本等于在大海捞针。

6.3 真实环境中遇到的经典事故

最后分享一个典型事故。某次我把 Agent 部署到测试环境，发现用户反复问同一个问题时，回答质量越来越差。排查过程很有意思：

第一阶段我以为是上下文爆了，检查 token 消耗，确实一路走高。但仔细看日志，发现问题是历史消息里积累了太多工具返回的检索结果，而且这些结果由于每次要求略有不同，不断互相矛盾。模型被这些互相冲突的信息干扰，逐渐陷入"左右为难"的状态。

解决办法不是单纯缩短历史，而是做"信息去重"——同一轮对话里，如果同一个工具被调用超过两次，只保留最后一次结果，并且对之前的工具结果做摘要合并。同时把系统提示词改成"如果本地检索结果与网络搜索结果矛盾，以时间更新的信息为准，并在回答中注明冲突点"。

这类问题有个共同特点：表面上是模型输出不准，实际上是你没有把"信息供给"设计好。Agent 的下游质量，很大程度上由上游信息的干净程度决定，这一点在测试阶段感受最深。

7. 你的第一个 Agent 应该如何优雅收尾

前面其实已经把构建 AI Agent 的完整技术路径走完了。从一个简单的 Python 脚本到具备工具调用、记忆管理和日志追踪的系统，整个过程你可以自己动手复现。我个人在实际开发中的体会是：

Agent 项目的核心能力，不是让模型"更聪明"，而是让模型在你的约束下"更可靠"。约束工具边界、压缩上下文、记录调用链路，每一样都比调 prompt 更见效。工具调用链的稳定胜过长任务的炫技，一个每次都能正确检索并回答明确引用来源的 Agent，比一个偶尔惊艳但经常跑偏的 Agent 更有价值。

最后再送你一个小技巧：给工具注册函数加一个validate_result参数。每次工具返回后，先让一个轻量级规则引擎检查结果结构，再决定是否传给模型。规则引擎代码量很小，但它能拦截掉大量因为模型输出异常而产生的"幻觉级回答"。Agent 的可靠性，就是这样一层一层垒起来的。