企业官网建设流程全解析

先别急着刷完 748 集，Agent 开发入门的正确姿势

打开 B 站搜索“AI Agent”，你大概率会看到各种“全套教程”“从入门到就业”“看完这一套就够了”的标题。这些视频动辄几百集，收藏夹吃灰率极高。问题不在于内容质量，而在于学习方式——Agent 开发不是靠“刷完”就能学会的，它和传统 CRUD 开发、前端开发、嵌入式开发有一个本质区别：你无法用“看完”来代替“做出来”。

这篇文章想解决的事情很明确：不劝你收藏任何一套 748 集的视频，而是帮你建立一个 Agent 开发的核心框架，让你知道 Agent 到底是什么、核心原理有哪些、入手应该选什么框架、怎么写第一个能跑通的 Agent，以及遇到问题应该去哪里排查。

文章不会很长，但每一段都值得你停下来想一想。如果你是一个刚接触 AI 应用开发的后端工程师、前端工程师，或者正在纠结要不要转 AI 方向的在校学生，这篇文章适合你。

1. 这篇关于 AI Agent 开发的文章，真正要解决什么

先给一个判断：Agent 开发是最近两年 AI 应用层最值得投入的方向，但它同时也是被误解最多的方向。

很多人以为 Agent 开发就是“调 API”，把 GPT-4 的接口接进来，加几句 system prompt 就算完事。如果你真这么做，做出来的东西顶多算一个“带提示词的聊天机器人”，和真正的 Agent 差得很远。

也有人以为 Agent 开发需要极强的算法背景，得先读三年论文才能动手。这也是误解。Agent 开发更多考验的是工程能力、任务拆解能力、对工具链的理解，而不是数学推导能力。你不需要从零训练模型，你需要的是把现有的大模型能力组合起来，解决一个具体业务问题。

那么，Agent 开发到底解决了什么真实痛点？

举一个非常常见的场景。假设你是公司里负责运维的工程师，每天要处理日志告警。过去你要写一堆 Python 脚本，手动登录服务器，执行命令，分析日志，再决定要不要告警。现在你可以做一个简单的 Agent：给大模型接上日志查询工具的 API，让模型自己判断“这个错误是什么级别”“要不要继续查上游服务状态”“最后生成一条告警摘要”。这个 Agent 能替你完成 80% 的重复判断，你只需要处理它筛出来的真正严重的问题。

类似的场景还有：客服工单自动分类、代码仓库的 PR Review 助手、企业内部知识库问答、SQL 查询生成与执行、爬虫数据清洗等等。

这些场景的共同点是：有明确的输入输出、有可调用的工具、有需要模型进行推理和判断的空间。

这就是 Agent 适合发挥的地方。

读完这篇文章，你将获得三条关键信息：

1. Agent 区别于传统程序的核心能力是什么。
2. Agent 开发的完整架构与常用框架选型。
3. 一条从零到第一个可运行 Agent 的最小实践路径。

2. 基础概念：Agent 不是聊天机器人，而是“会用工具的程序”

要理解 Agent 开发，必须先理解几个概念。这节会尽量用大白话讲清楚。

2.1 LLM：Agent 的大脑

LLM（Large Language Model，大语言模型）是 Agent 的“大脑”。它负责理解用户的意图、生成计划、做出决策。没有 LLM 的 Agent 只是传统自动化脚本，有了 LLM 的 Agent 才能“自己拿主意”。

但 LLM 有一个天然短板：它只会“想”和“说”，不会“做”。让 GPT-4 写一段代码它可以写得很好，但你让它直接去执行这段代码、读取你本地的文件、调用你的数据库，它就无能为力了。除非你给它接上工具。

2.2 Tool：Agent 的手和脚

Tool（工具）是 Agent 能对外部世界产生影响的手段。一个工具可以是一个函数、一个 API 接口、一个数据库查询、一个命令行执行器。

举个例子。如果你给 Agent 接了一个search_web(query)工具，它就能回答超出它训练数据时效的问题。如果你给它接了一个execute_sql(sql)工具，它就能查你公司的数据库。如果你给它接了一个send_email(to, subject, body)工具，它就能代替你发邮件。

工具是 Agent 与外部世界交互的唯一方式。这也是 Agent 开发与传统开发最大的不同：你不是把逻辑写死在代码里，而是把工具提供给模型，让模型自己决定调用哪个、什么时候调用、怎么传参数。

2.3 Planning：Agent 的思考方式

Planning（规划）是 Agent 最像“智能体”的部分。当用户给一个复杂任务时，Agent 不是直接调用工具，而是先拆解任务。比如用户说“帮我分析这个月的销售数据，找出下滑原因，并写一份报告”，Agent 会先规划：

• 第一步：找到销售数据表。
• 第二步：写 SQL 查询月度销售趋势。
• 第三步：分析哪个产品线下滑最明显。
• 第四步：搜索可能的竞品动态（如果有联网工具）。
• 第五步：生成报告。

这个能力来自模型本身，但也可以用代码方式强约束。常见的规划方式有两种：一种是让模型自由发挥（ReAct 模式），另一种是在代码中定义好流程图（Plan-and-Execute 模式）。后面会详细说。

2.4 Memory：Agent 的短期记忆与长期记忆

Memory（记忆）决定了 Agent 能不能记得“上下文”。有两种记忆需要区分：

• Context Window（上下文窗口）：模型一次能处理的最大 token 数。这是“短期记忆”。
• Vector Store（向量数据库）：把历史信息存成向量，需要时检索回来。这是“长期记忆”。

没有记忆的 Agent 每次调用都是“失忆”的。有了记忆，Agent 才能在多轮对话中保持一致性，或者从历史经验中学习。

2.5 什么是真正意义上的 Agent

综合上面几个概念，可以给 Agent 下一个严格的定义：

Agent = LLM + Planning + Tool + Memory

这四者缺一不可。如果你的程序只用了 LLM 做文本生成，没有调用工具，也没做规划，那它只是一个聊天机器人。如果你的程序用了 LLM 做意图识别，但决策逻辑全写在代码里，那它只是一个加了 NLP 模块的传统程序。只有当你让 LLM 在循环中决定“下一步做什么、调用什么工具”，你才算在开发 Agent。

这个概念非常重要，因为很多人学了很久 Agent 开发，做出来的东西却只是“LLM API 的壳子”。

2.6 Agent 与 Workflow 的区别

还有一个容易混淆的概念是 Workflow。Workflow（工作流）是把步骤写死在代码里，比如“用户输入 -> 调用模型 -> 输出结果”，每一步顺序固定。而 Agent 是在运行时动态决定下一步做什么。前者适合流程稳定、不需要太多智能判断的场景；后者适合开放性强、步骤不确定的场景。

实际项目中，两者常常混用。主流框架推荐的模式是：用 Workflow 控制主流程，在需要模型决策的地方用 Agent。这种混合架构在稳定性与灵活性之间取得了平衡，也是我建议初学者采用的方式。

对于初学者，我的建议是：先别急着追求“纯 Agent”，先用 Workflow 的方式跑通一个任务，然后逐步把需要推理判断的节点替换成 Agent。

3. Agent 开发环境准备与前置条件

在写第一个 Agent 之前，先把环境准备好。这里以一个常见的技术栈为例。

3.1 环境清单

Agent 开发并不需要多高端的机器。你本地的电脑足够跑通大部分开源 Agent 框架和调用云 API 的示例。以下是推荐的环境和工具组合：

这里要特别说明一下：文章中的代码示例主要使用 Python 3.10+ 和 LangChain 风格代码。版本号以你实际安装时的最新稳定版为准，不建议盲从旧教程使用已弃用的类名和方法。

3.2 安装 Python 虚拟环境

Python 项目依赖很容易出现版本冲突，所以强烈建议在每个项目里建立虚拟环境。以创建agent-dev项目为例：

mkdir agent-dev cd agent-dev python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate

激活虚拟环境后，你的命令行提示符前面会出现(venv)，表示当前处于虚拟环境内。后续安装的包都只会装在这个目录里，不会污染系统 Python。

3.3 安装核心依赖

先安装最基础的依赖：

pip install --upgrade pip pip install langchain langchain-openai python-dotenv

如果你计划使用本地模型做实验，还需要安装 Ollama，并下载一个小体积模型。示例命令如下：

# 安装 Ollama（macOS / Linux） curl -fsSL https://ollama.com/install.sh | sh # 拉取一个轻量模型 ollama pull qwen2.5:7b

说明：如果你的网络环境访问外网模型服务有困难，可以优先使用国内可用的模型 API 或本地 Ollama。代理与网络配置相关问题本文不涉及，请在自己合法的网络环境中进行实验。

3.4 配置模型 API 密钥

在项目根目录创建.env文件，把 API 密钥放进去。注意：这个文件不要提交到 Git。

# .env OPENAI_API_KEY=sk-your-key-here # 如果使用其他兼容 OpenAI 接口的模型服务，可增加以下配置 OPENAI_BASE_URL=https://your-endpoint.example.com/v1

然后在代码中加载这个文件：

# config.py import os from dotenv import load_dotenv load_dotenv() api_key = os.getenv("OPENAI_API_KEY")

如果你的密钥前缀是其他平台的，同样通过环境变量管理。保持密钥不写入代码的习惯，是生产环境的基本要求。

到这里，环境就准备好了。接下来进入核心流程。

4. Agent 开发核心流程拆解

这一节会拆解开发一个完整 Agent 的通用流程。不管用的是 LangChain、LlamaIndex、AutoGen 还是自研框架，底层的思考方式是一致的。

4.1 定义任务目标与边界

写代码之前，先想清楚：你的 Agent 到底要解决什么问题？输入是什么？输出是什么？允许调用哪些工具？不允许调用哪些工具？

以“日志智能分析 Agent”为例：

任务：根据用户输入的日志片段或日志查询条件，自动分析异常原因并输出排查建议 输入：日志文本或查询条件 输出：异常摘要、可能原因、排查建议 允许工具：日志查询 API、代码解释器 不允许工具：发送邮件、删除日志

这个边界定义非常重要。没有边界，模型可能会在运行时做出你不想让它做的事情。Agent 开发中常见的“Prompt Injection（提示注入）”风险，很大程度上要通过边界约束来缓解。

4.2 选择基础模型与调用方式

选择模型的时候，主要考虑几个因素：

• 推理能力：复杂任务需要更强推理能力的模型。
• 上下文窗口：处理超长文本时窗口要大。
• 工具调用支持：尽量选择原生支持 Function Calling / Tool Calling 的模型，开发效率会高很多。
• 响应速度与成本：生产环境要评估。

目前主流模型基本都支持工具调用。如果你用的是国产模型 API，建议查阅对应文档确认工具调用的开通方式。

4.3 定义工具集

工具定义是 Agent 开发中工作量最大的部分之一。每个工具都要写清楚：

• 工具名称：模型调用时用的标识。
• 描述：告诉模型这个工具是干什么的、什么时候用。
• 参数结构：使用时需要传入哪些参数。
• 执行逻辑：实际调用的函数体。

举例，写一个“查询城市天气”的工具：

import json from typing import Type from langchain_core.tools import BaseTool from pydantic import BaseModel, Field class WeatherInput(BaseModel): city: str = Field(description="城市名称，比如北京、上海") class WeatherTool(BaseTool): name: str = "get_weather" description: str = "查询指定城市当前天气情况，适用于用户问天气时" args_schema: Type[BaseModel] = WeatherInput def _run(self, city: str) -> str: # 这里应该调用真实天气 API，示例直接返回模拟数据 weather_data = {"北京": "晴，22-30℃", "上海": "多云，25-31℃"} result = weather_data.get(city, "暂不支持该城市查询") return json.dumps({"city": city, "weather": result}, ensure_ascii=False)

工具描述写得好不好，直接决定模型能不能在正确时机调用它。描述太笼统，模型就会犹豫；描述太具体，模型反而会局限。这是一个需要反复调优的部分。

4.4 设计记忆与上下文管理

如果你的 Agent 是多轮对话型的，必须考虑记忆问题。一种简单的做法是：把对话历史直接塞进 prompt。但上下文窗口有限，塞不了太多轮。更高级的做法是：

• 短期记忆：保留最近 N 轮对话。
• 长期记忆：把重要的历史信息抽取嵌入到向量数据库。
• 摘要记忆：每几轮对话生成一次摘要，替代原始记录。

在第一个项目里，建议先用短期记忆，跑通之后再加向量数据库。

4.5 实现主循环

Agent 的核心是一个循环，简单描述为：

1. 接收用户输入。
2. 把输入、历史、工具描述一起交给模型。
3. 模型返回“回答”或“工具调用请求”。
4. 如果模型决定调用工具，执行工具，把结果返回给模型。
5. 模型基于工具结果继续生成，回到第 2 步。
6. 直到模型给出最终答案，循环结束。

这个模式通常叫 ReAct（Reason + Act）。本质上就是让模型一边推理一边行动，直到完成任务。

下面用一个最小实现来演示这个循环。

5. 完整示例：零依赖实现一个可运行的 Agent

考虑到初学者可能对框架有认知负担，这一节先不引入 LangChain 等重框架，而是用 Python 直接调用 OpenAI 兼容的 API，实现一个最简单的支持工具调用的 Agent。这样做能帮助你理解 Agent 的底层逻辑，不会因为框架封装太深而变成“只会调包”。

5.1 项目结构

agent-minimal/ ├── .env ├── config.py ├── tools.py ├── agent.py └── requirements.txt

5.2 安装依赖

pip install openai python-dotenv

5.3 定义工具

创建一个简单的“伪计算器”工具和一个“获取当前时间”工具：

# tools.py import datetime import json def calculator(expression: str) -> str: """执行简单的四则运算表达式。""" try: result = eval(expression, {"__builtins__": {}}, {}) return json.dumps({"result": result}, ensure_ascii=False) except Exception as e: return json.dumps({"error": str(e)}, ensure_ascii=False) def get_current_time() -> str: """返回当前系统时间。""" now = datetime.datetime.now() return json.dumps({"time": now.strftime("%Y-%m-%d %H:%M:%S")}, ensure_ascii=False) # 工具注册表：名字 -> (函数, 描述) TOOLS = { "calculator": { "function": calculator, "description": "执行四则运算的数学计算器，输入为数学表达式字符串", }, "get_current_time": { "function": get_current_time, "description": "获取当前系统日期和时间，无输入参数", }, }

这里特别注意：eval有安全隐患，仅用于本地演示。实际项目中，工具的代码要经过严格的安全审查，涉及执行动态代码的能力要非常谨慎。

5.4 实现 Agent 主循环

# agent.py import json import os from openai import OpenAI from dotenv import load_dotenv from tools import TOOLS load_dotenv() client = OpenAI( api_key=os.getenv("OPENAI_API_KEY"), base_url=os.getenv("OPENAI_BASE_URL"), ) SYSTEM_PROMPT = """ 你是智能助手。你可以使用以下工具来帮助用户： {} 当用户需要调用工具时，必须输出一个 JSON 对象，格式如下： {{"tool": "工具名", "args": {{"参数名": "参数值"}}}} 不要输出任何其他文字。 当没有合适的工具时，直接回答用户。 """.format(json.dumps(TOOLS, ensure_ascii=False, default=str)) def run_agent(user_input: str, max_steps: int = 5): messages = [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": user_input}, ] for step in range(max_steps): response = client.chat.completions.create( model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"), messages=messages, temperature=0.2, ) content = response.choices[0].message.content.strip() print(f"[思考第 {step + 1} 步]", content) # 尝试解析 JSON，判断是否需要调用工具 try: parsed = json.loads(content) tool_name = parsed.get("tool") tool_args = parsed.get("args", {}) except json.JSONDecodeError: print(">>> 最终回答：", content) return content if tool_name not in TOOLS: print(">>> 未知工具，直接回答：", content) return content # 调用工具 tool_func = TOOLS[tool_name]["function"] try: tool_result = tool_func(**tool_args) except Exception as e: tool_result = json.dumps({"error": str(e)}, ensure_ascii=False) print(f"[工具结果] {tool_name} -> {tool_result}") # 把工具结果追加到对话中 messages.append({"role": "assistant", "content": content}) messages.append({"role": "user", "content": f"工具执行结果：{tool_result}。请根据结果继续回答或给出最终结论。"}) print(">>> 达到最大步数，停止执行") return None if __name__ == "__main__": test_input = "现在几点钟？顺便帮我计算 (15 + 23) * 2 等于多少。" run_agent(test_input)

5.5 运行与测试

python agent.py

预期输出类似：

[思考第 1 步] {"tool": "get_current_time", "args": {}} [工具结果] get_current_time -> {"time": "2025-06-15 14:30:22"} [思考第 2 步] {"tool": "calculator", "args": {"expression": "(15 + 23) * 2"}} [工具结果] calculator -> {"result": 76} [思考第 3 步] 当前时间是 2025-06-15 14:30:22。你让我计算的 (15 + 23) * 2 结果是 76。 >>> 最终回答： 当前时间是 2025-06-15 14:30:22。你让我计算的 (15 + 23) * 2 结果是 76。

这说明 Agent 成功实现了“推理 -> 行动 -> 观察结果 -> 继续推理”的循环。

这个最小示例有两个明显的缺点：一是没有引入成熟的工具调用协议，只是在 prompt 里要求模型输出 JSON；二是很容易出现解析失败的情况。生产环境不建议这么写，推荐用框架自带的 Function Calling 支持。

6. 使用 LangChain 实现更规范的 Agent

理解原理之后，再看框架就轻松很多。LangChain 是目前 Agent 开发中使用最广泛的框架之一，它把很多底层工作标准化了。

6.1 安装 LangChain 相关依赖

pip install langchain langchain-openai

6.2 使用工具调用能力的 Agent 示例

这里实现一个相同的功能，但使用 LangChain 的create_tool_calling_agent方式，这种方式与模型的 native tool calling 协议对接，效果更稳定。

# langchain_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate load_dotenv() # 1. 定义工具 @tool def calculator(expression: str) -> str: """适用于执行四则运算。输入一个数学表达式。""" try: result = eval(expression, {"__builtins__": {}}, {}) return str(result) except Exception as e: return f"计算错误: {e}" @tool def get_current_time() -> str: """获取当前日期时间。""" from datetime import datetime return datetime.now().strftime("%Y-%m-%d %H:%M:%S") # 2. 初始化模型 llm = ChatOpenAI( model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"), api_key=os.getenv("OPENAI_API_KEY"), base_url=os.getenv("OPENAI_BASE_URL"), ) # 3. 构建 Prompt prompt = ChatPromptTemplate.from_messages([ ("system", "你是可靠的助手，使用工具帮助用户解决问题。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) # 4. 创建 Agent tools = [calculator, get_current_time] agent = create_tool_calling_agent(llm, tools, prompt) agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True) # 5. 运行 if __name__ == "__main__": response = agent_executor.invoke({"input": "现在几点了？帮我算 (15 + 23) * 2"}) print("最终输出：", response)

运行方式：

python langchain_agent.py

verbose=True会在控制台打印出 Agent 的每一步推理和工具调用过程，这是学习 Agent 开发最重要的调试手段之一。你会看到模型“思考”了哪些步骤、调用哪个工具、工具返回了什么、最终如何给出答案。

6.3 关键配置项的解释

LangChain 的 AgentExecutor 有几个参数值得注意：

• max_iterations：限制最大迭代步数，防止模型陷入无限循环，建议设置为 3 到 10。
• early_stopping_method：达到最大步数时的处理方式，默认是force生成一个回答。
• handle_parsing_errors：解析错误时如何处理，建议开启。
• return_intermediate_steps：是否在结果中返回中间步骤，便于追踪。生产环境建议开启配合日志系统。

一个更安全的配置示例：

agent_executor = AgentExecutor( agent=agent, tools=tools, verbose=True, max_iterations=5, handle_parsing_errors=True, return_intermediate_steps=True, )

7. 主流 Agent 开发框架选型与对比

LangChain 并不是唯一选择。不同的项目规模、团队技术栈和业务场景，适合不同的框架。这里做一个客观对比。

一个常见误区是：初学者一上来就选“最强大”的框架。实际上，如果任务场景并不复杂，用 Coze 甚至简单的 API 调用就能解决，不必引入 LangChain 的重型编排能力。框架选型应该遵循“从简到繁”的原则。

针对不同技术背景的开发者，我给出如下建议：

• 后端 Java/C++ 背景：优先考虑 LangChain4j 或者直接用 Python LangChain，原因是你主力语言可能不是 Python，Python 生态更适合 AI 开发，可以先用 Python 做原型，后续再用 Java 重构。
• 前端角色：如果不懂后端，可以考虑先学 Coze/Dify，用低代码方式感受 Agent 逻辑，再逐步学习 Python。
• 算法背景：直接上 LlamaIndex + LangGraph，配合自己的模型能力做效果调优。

8. Agent 开发进阶方向：RAG、多 Agent 与 Agent Skills

8.1 RAG（检索增强生成）

RAG 是 Agent 开发中绕不开的方向。它的核心思想是：用户提问时，不是直接让模型生成，而是先从知识库中检索相关文档片段，再把文档片段作为上下文交给模型生成答案。这样做的好处是：

• 回答基于事实资料，减少幻觉。
• 可以接入企业私有知识库。
• 数据更新不需要重新训练模型。

RAG 的基本链路是：文档加载 -> 文本切分 -> 向量化 -> 向量存储 -> 检索 -> LLM 生成。在实现 Agent 时，RAG 往往作为一个“知识检索工具”接入 Agent 中。

8.2 多 Agent 协作

当单一 Agent 难以处理复杂任务时，可以考虑多 Agent 架构。有几种常见模式：

• 主管-工人模式：一个“主管 Agent”负责拆解任务，分派给多个“工人 Agent”执行。
• 辩论模式：多个 Agent 对同一问题提出不同观点，最终汇总结论。
• 流水线模式：一个 Agent 的输出是另一个 Agent 的输入。

多 Agent 的好处是每个 Agent 可以专注在自己的领域，降低单个 prompt 的复杂度。但代价是 token 消耗增加、调试难度上升。新手不建议一上来就做多 Agent，先保证单个 Agent 稳定可靠再说。

8.3 Agent Skills 与工具扩展

“Skills”这个词在最近的 Agent 生态里很流行，它本质上是一组可供 Agent 复用的技能包，可以包含工具函数、prompt 模板、调用规范。比如“SQL 查询技能”可以包含如何连接数据库、如何校验 SQL 安全性、如何格式化查询结果等多个能力。

可以简单理解：一个 Skill 是“工具 + 使用说明 + 约束条件”的打包。它让 Agent 在面对某类任务时，不只是一个孤立的函数，而是有一套完整的方法论。

实际开发中，建议把工具按场景归类，每个场景维护一个 Skill 包。这不仅能提高复用性，也方便做版本管理和测试。

9. 常见问题与排查思路

Agent 开发与传统开发在调试上有很大不同。模型的不确定性导致代码“看起来没报错，但结果不对”的情况非常常见。以下按出现频率排序最典型的几个问题。

调试 Agent 有一个核心原则：先看日志，再猜原因。模型输出永远是排查的第一现场。很多“诡异问题”其实只要打开verbose=True看一遍中间过程就立刻明白了。

10. 最佳实践与工程建议

从“能跑通 Demo”到“能上线生产”，Agent 开发还有一段距离。下面这些规范是我认为值得提前养成的习惯。

10.1 安全边界：永远假设模型不可信

Agent 的决策来自模型输出，而模型输出是不可完全预测的。这要求开发者必须在代码层面设置安全边界：

• 工具注册表白名单化，禁止模型动态创建工具。
• 涉及系统命令、文件删除、支付、发邮件等高危操作，一律走人工审批流。
• 对模型的工具调用参数做校验和过滤。
• 不要轻易把外部输入直接拼接到 prompt 中，防止提示注入。

10.2 成本控制：每一次工具调用都是钱

Agent 是多轮循环，每轮都要调用一次模型，这意味着一个复杂任务可能要消耗大量 token。控制成本的手段包括：

• 设置max_iterations上限。
• 缓存中间结果，对相同输入直接返回。
• 使用更小、更便宜的模型处理简单任务。
• 为不同工具编写更精炼的描述，减少模型“犹豫”带来的多余调用。

10.3 可观测性：日志是 Agent 的唯一真相

生产环境的 Agent 必须记录完整调用链路。建议至少记录以下信息：

• 用户原始输入。
• 系统 prompt 版本。
• 每轮模型输出（思考过程）。
• 工具调用名称、参数、返回结果、耗时。
• 最终回答。
• 总 token 消耗。

有了这些日志，才能对 Agent 的效果进行评估、归因和持续优化。

10.4 评估体系：用什么指标判断 Agent 好坏

一个 Agent 上线之前必须建立评测集。最简单的做法是准备 20 到 50 个典型问题，人工标注期望输出，每次改动 prompt 或模型后都跑一遍评测集，对比结果。可参考的指标包括：

• 任务成功率：最终结果是否满足用户需求。
• 工具调用准确率：是否在正确场景调用了正确工具。
• 无回复率：模型是否频繁承认自己不会。
• 平均轮数：完成一个任务需要多少次模型调用，轮数越少成本越低。
• 幻觉率：生成内容是否有事实错误（需要人工抽查）。

10.5 版本管理：Prompt 变更也要走 Git

把系统 prompt 当作代码的一部分，写入 Git 仓库。每次修改都记录变更原因。在实际项目中，prompt 的迭代频率远高于业务代码，如果没有任何版本管理，很容易出现“昨天还能用，今天突然不行了”但找不到原因的情况。更严谨的团队会把 prompt 存放在配置中心，线上动态调整，避免改 prompt 需要重新发布服务。

10.6 个人开发者学习路线建议

如果你是初学者，按下面的路径走，投入产出比最高：

1. 用 Coze 或 Dify 画一个可视化 Agent，感受“模型 + 工具”的组合。
2. 用 Python + OpenAI SDK 写一个不支持工具调用的极简 Agent（比如 5.3 节的版本）。
3. 用 LangChain 做一个支持工具调用的 Agent，理解AgentExecutor的结构。
4. 给 Agent 加上 RAG 能力，做一个“私有知识库问答机器人”。
5. 尝试把 Agent 的日志、记忆、评估体系完善起来。
6. 用 FastAPI 把 Agent 封装成 HTTP 服务，供前端或其他系统调用。

走到第 5 步时，你已经超过 90% 的“收藏党”了。不需要看过任何一套 748 集的视频。

11. 总结与下一步建议

这篇文章讨论的核心其实是两件事：第一，Agent 开发的本质是让 LLM 在循环中调用工具解决开放性问题，它不是简单的 API 调用；第二，Agent 入门的正确路径是先理解原理，再动手做最小实现，然后引入成熟框架，最后考虑工程化。

如果你现在刚看完这篇文章，下一步可以从一个非常小的场景开始：比如做一个“桌面便签助手”，让 Agent 能创建、查询、删除本地文件中的笔记。这个项目用不了多少行代码，但能让你完整经历工具定义、记忆管理、多轮对话、排错的全过程。

真正值得投入精力的方向是：RAG 在垂直领域的落地、多 Agent 协作的生产级可靠性、Agent 的可观测性与评测体系。这几个方向在未来两三年里都会有持续的需求。

对于那些收藏了“全套教程”的朋友，我的建议是：不要试图看完，直接找到第 20 集左右的“第一个实战项目”，跟着做一遍；卡住了再回看。用项目倒逼学习，比线性刷视频有效得多。

动手做一个能跑的 Agent，胜过收藏十套教程。