企业官网建设流程全解析

1. 从零理解Agent：它到底能帮你做什么

1.1 一个真实场景引发的思考

去年年底，我接手了一个需求：每周需要从十几个不同的数据源抓取信息，整理成一份结构化报告，再根据报告内容自动生成摘要和行动建议。最开始我写了一个Python脚本，用requests加BeautifulSoup硬编码每个数据源的解析逻辑。结果呢？第一个月还能跑，第二个月开始，有三个数据源的页面结构改了，两个接口返回格式变了，还有一个直接加了动态渲染。我花了整整两天时间改代码，改完之后我就想：这东西能不能自己适应变化？

这就是Agent要解决的核心问题。传统的自动化脚本是“死”的，你告诉它第一步做什么、第二步做什么，它就照着执行，遇到没预料到的情况就崩溃。而Agent是“活”的，你给它一个目标，它自己决定用什么工具、按什么顺序、怎么处理异常。打个比方，传统脚本像是一份精确到秒的列车时刻表，Agent更像是一个有经验的司机，知道目的地在哪里，路上遇到堵车会自己绕路。

1.2 Agent的最小定义与核心能力

我不打算搬教科书上的定义，用我自己的话说：Agent就是一个能感知环境、做出决策、执行动作、并根据反馈调整策略的智能体。它和普通程序最大的区别在于“决策”这两个字。普通程序的决策逻辑是你写死的if-else，Agent的决策逻辑是基于大语言模型的推理能力动态生成的。

一个能跑通任务的Agent，至少需要四个核心模块：

• 规划模块：把用户给的高层目标拆解成可执行的子任务。比如“帮我调研一下某个行业的市场规模”这个目标，需要拆解成“确定调研维度→搜索数据源→提取关键数据→交叉验证→生成报告”这样的步骤。
• 工具调用模块：Agent不能只会聊天，它得能干活。搜索、读写文件、调用API、执行代码，这些都是工具。工具调用的关键是让模型知道“什么时候该用哪个工具”。
• 记忆模块：短期记忆负责记住当前任务的上下文，长期记忆负责存储历史经验和用户偏好。没有记忆的Agent就像金鱼，每次对话都从零开始。
• 执行循环：Agent不是一次推理就结束的，它需要“思考→行动→观察→再思考”的循环。这个循环的质量直接决定了任务能不能跑通。

1.3 谁适合上手Agent开发

如果你满足以下任意一条，这篇内容就是写给你的：

• 有Python基础，想从传统开发转向AI应用开发
• 已经在用大模型API做应用，但发现单次调用解决不了复杂问题
• 对自动化流程有需求，但不想维护一堆脆弱的脚本
• 想理解Agent的工作原理，而不是只会调包

我下面会从环境搭建开始，一步步带你跑通一个完整的Agent任务。不跳步骤，不省略细节，所有代码都可以直接复制运行。

2. 环境搭建与工具选型：别在第一步就踩坑

2.1 开发环境的最小依赖

先把环境搞干净。我强烈建议用虚拟环境，别在系统Python里直接装包，不然后面版本冲突会让你怀疑人生。

python -m venv agent-env source agent-env/bin/activate # Windows用 agent-env\Scripts\activate

核心依赖其实不多，但版本要锁死。我踩过的坑是：某个Agent框架对Pydantic的版本极其敏感，Pydantic v1和v2的API完全不兼容，装错了直接报一堆看不懂的错。

pip install openai>=1.30.0 pip install pydantic>=2.0.0 pip install httpx>=0.27.0 pip install rich>=13.0.0 # 终端输出美化，调试时很有用

如果你要用本地模型，还需要装对应的推理框架，但那是另一个话题了。第一次跑通Agent，我建议直接用云端API，省去环境配置的麻烦。

2.2 模型选型的三个关键维度

选模型不是越贵越好，也不是参数越大越好。我一般从三个维度评估：

我实测下来，对于大多数Agent任务，中等推理能力的模型已经够用了。真正影响任务成功率的，往往不是模型本身，而是你的提示词设计和工具定义质量。

2.3 框架选择：从零手写还是用现成的

这是新手最容易纠结的问题。我的建议是：第一次跑通，手写；后续迭代，用框架。

为什么？因为手写一遍你才能真正理解Agent的执行循环。框架帮你封装了很多东西，但出了问题你根本不知道从哪里排查。我见过太多人用LangChain搭了个Agent，结果工具调用一直失败，查了半天发现是提示词模板里有个隐藏的格式问题。

手写一个最小Agent，核心代码不超过200行。等你理解了每个环节在做什么，再去用框架，效率会高很多。下面我就带你手写一个。

3. 手写一个最小可用Agent：200行代码跑通完整任务

3.1 核心架构设计

我们的Agent需要完成这样一个任务：给定一个主题，自动搜索相关信息，提取关键数据，生成一份结构化摘要。

架构分四层：

1. LLM层：负责推理和决策，调用大模型API
2. 工具层：定义Agent可以使用的工具，包括搜索、文件读写、代码执行
3. 记忆层：维护对话历史和任务状态
4. 循环层：驱动“思考→行动→观察”的循环

先定义工具。工具的本质是一个函数，加上一段描述告诉模型这个函数是干什么的、参数是什么。

import json import httpx from typing import Callable class Tool: def __init__(self, name: str, description: str, func: Callable): self.name = name self.description = description self.func = func def to_schema(self): """转换成模型能理解的工具描述格式""" return { "type": "function", "function": { "name": self.name, "description": self.description, "parameters": { "type": "object", "properties": self._get_params(), "required": self._get_required() } } }

这里有个关键点：工具描述的质量直接决定模型能不能正确调用。我见过很多人写工具描述就一句话“搜索信息”，模型根本不知道什么时候该用、参数怎么传。好的工具描述应该包含：这个工具做什么、什么时候用、参数的含义和格式、返回什么。

3.2 工具定义与实现

我们定义三个核心工具：

def search_web(query: str, max_results: int = 5) -> str: """模拟搜索工具，实际使用时替换成真实的搜索API""" # 这里用模拟数据演示，实际接入搜索API results = [ {"title": f"关于{query}的研究报告", "snippet": f"这是关于{query}的详细分析..."}, {"title": f"{query}行业数据", "snippet": f"最新数据显示{query}市场规模达到..."}, ] return json.dumps(results[:max_results], ensure_ascii=False) def save_to_file(filename: str, content: str) -> str: """保存内容到文件""" with open(filename, 'w', encoding='utf-8') as f: f.write(content) return f"已保存到{filename}" def read_file(filename: str) -> str: """读取文件内容""" try: with open(filename, 'r', encoding='utf-8') as f: return f.read() except FileNotFoundError: return f"文件{filename}不存在"

工具定义好之后，注册到Agent里：

tools = [ Tool("search_web", "搜索互联网获取信息。当需要查找资料、数据、新闻时使用。参数query是搜索关键词。", search_web), Tool("save_to_file", "将内容保存到本地文件。当需要持久化存储结果时使用。参数filename是文件名，content是内容。", save_to_file), Tool("read_file", "读取本地文件内容。当需要查看已保存的文件时使用。参数filename是文件名。", read_file), ]

3.3 提示词设计：Agent的大脑

提示词是Agent的灵魂。我试过很多版本，最后稳定下来的结构是这样的：

SYSTEM_PROMPT = """你是一个任务执行Agent。你的目标是帮助用户完成指定的任务。 你可以使用以下工具： {tool_descriptions} 工作流程： 1. 分析用户的任务，确定需要哪些步骤 2. 每一步选择一个工具执行，等待结果 3. 根据结果决定下一步 4. 当任务完成时，输出最终结果 重要规则： - 每次只调用一个工具 - 调用工具前先说明你的思考过程 - 如果工具返回错误，尝试其他方法 - 任务完成后用"任务完成"标记结束 当前任务：{task} """

这个提示词有几个关键设计：

• 明确工作流程：告诉模型先分析、再执行、再判断，避免它一上来就乱调工具
• 限制每次只调一个工具：并行调用虽然快，但调试难度成倍增加，新手先跑通串行
• 要求说明思考过程：这不仅是为了可解释性，更重要的是让模型“想清楚再动手”，实测能显著降低错误率
• 错误处理指引：明确告诉模型工具报错了该怎么办，不然它可能直接卡死

3.4 执行循环的实现

这是Agent最核心的部分：

import openai client = openai.OpenAI(api_key="你的API Key") def run_agent(task: str, max_steps: int = 10): messages = [ {"role": "system", "content": SYSTEM_PROMPT.format( tool_descriptions=format_tools(tools), task=task )} ] for step in range(max_steps): # 1. 调用模型进行推理 response = client.chat.completions.create( model="gpt-4o-mini", # 替换成你用的模型 messages=messages, tools=[t.to_schema() for t in tools], tool_choice="auto" ) msg = response.choices[0].message messages.append(msg) # 2. 检查是否有工具调用 if not msg.tool_calls: # 没有工具调用，说明模型认为任务完成了 print(f"最终结果：{msg.content}") return msg.content # 3. 执行工具调用 for tool_call in msg.tool_calls: tool_name = tool_call.function.name tool_args = json.loads(tool_call.function.arguments) print(f"[步骤{step+1}] 调用工具：{tool_name}，参数：{tool_args}") # 找到对应的工具并执行 tool = next((t for t in tools if t.name == tool_name), None) if tool: try: result = tool.func(**tool_args) except Exception as e: result = f"工具执行错误：{str(e)}" else: result = f"未知工具：{tool_name}" # 4. 将结果返回给模型 messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": str(result) }) return "达到最大步数限制，任务未完成"

这段代码就是Agent的心脏。它的逻辑很直白：模型思考→决定调工具→执行工具→把结果喂回模型→模型继续思考。循环直到模型不再调工具，或者达到步数上限。

3.5 第一次运行：踩坑记录

我第一次跑的时候，遇到了几个典型问题：

问题一：模型不调工具，直接编答案。我问它“帮我搜索一下最新的行业数据”，它直接给我编了一段看起来很像真的但完全是虚构的数据。原因是我在提示词里没有强调“必须使用工具获取信息”。后来我加了一句“所有事实性信息必须通过工具获取，禁止凭记忆回答”，问题解决了。

问题二：工具参数格式错误。模型传过来的参数有时候是字符串，有时候是数字，有时候嵌套了一层。我在工具函数里加了参数校验和类型转换，才稳定下来。

问题三：无限循环。模型调了搜索工具，拿到结果后觉得不满意，又调了一次同样的搜索，来回好几次。我在提示词里加了“同一个工具用相同参数最多调用一次”的规则，同时在代码里加了调用记录去重。

提示：第一次跑Agent，建议把max_steps设小一点，比如5步。这样即使出问题也能快速失败，不会浪费太多token。

4. 从能跑到好用：Agent的进阶优化

4.1 记忆管理：让Agent记住上下文

基础版的Agent每次任务都是从零开始，没有记忆。但在实际使用中，用户往往需要多轮交互。比如第一轮让Agent调研某个主题，第二轮让它基于调研结果写报告。如果Agent不记得第一轮的结果，第二轮就得重新调研。

短期记忆的实现比较简单，就是把对话历史维护好。但这里有个坑：上下文长度是有限的。当对话轮次多了，历史消息会超出模型的上下文窗口。我的做法是保留最近N轮对话，同时把更早的对话压缩成摘要。

class Memory: def __init__(self, max_recent: int = 10): self.recent_messages = [] self.summary = "" self.max_recent = max_recent def add(self, message): self.recent_messages.append(message) if len(self.recent_messages) > self.max_recent: # 把最早的消息压缩成摘要 old = self.recent_messages.pop(0) self.summary += f"\n历史：{old.get('content', '')[:100]}" def get_context(self): context = [] if self.summary: context.append({"role": "system", "content": f"历史摘要：{self.summary}"}) context.extend(self.recent_messages) return context

长期记忆可以用向量数据库实现，把重要的信息存进去，需要的时候检索出来。但这属于进阶内容，第一次跑通不需要。

4.2 错误处理与重试机制

Agent执行任务时出错是常态，不是异常。网络超时、API限流、工具返回格式不对，这些都会发生。关键是怎么优雅地处理。

我的策略是三层防护：

• 第一层：工具内部处理。工具函数自己捕获可预期的异常，返回友好的错误信息而不是直接抛异常。
• 第二层：Agent循环处理。当工具返回错误时，把错误信息喂回模型，让它决定是重试、换工具还是放弃。
• 第三层：外层兜底。设置最大重试次数和超时时间，防止无限循环。

def execute_with_retry(tool, args, max_retries=2): for attempt in range(max_retries + 1): try: return tool.func(**args) except Exception as e: if attempt == max_retries: return f"工具执行失败（已重试{max_retries}次）：{str(e)}" time.sleep(1 * (attempt + 1)) # 指数退避

4.3 提示词优化：从能用到好用

基础提示词能让Agent跑起来，但要让它在复杂任务上稳定工作，提示词需要精细打磨。我总结了几个实用的优化技巧：

技巧一：给示例。在提示词里放一两个完整的任务执行示例，模型会模仿这个模式。这比单纯描述规则有效得多。

技巧二：分步骤引导。对于复杂任务，不要让模型一次性规划所有步骤。而是引导它“先做第一步，做完告诉我结果，我再告诉你下一步”。这样虽然交互轮次多了，但每一步的准确率大幅提升。

技巧三：输出格式约束。明确告诉模型输出什么格式。比如“用JSON格式输出，包含summary和key_points两个字段”。格式约束能减少解析错误。

技巧四：角色设定。给Agent一个具体的角色，比如“你是一个资深行业分析师”，比“你是一个助手”效果好很多。角色设定会影响模型的语气、深度和关注点。

4.4 工具设计的经验法则

工具设计有几个我踩过坑之后总结的原则：

注意：工具的数量不是越多越好。我建议初期控制在5个以内。工具太多会导致模型选择困难，反而降低准确率。

5. 常见问题排查与实战避坑指南

5.1 模型不调用工具怎么办

这是最高频的问题。模型宁愿自己编答案也不调工具，通常有三个原因：

原因一：提示词没有强制要求。解决方法是加一句“所有事实性信息必须通过工具获取，禁止凭记忆回答”。如果还不行，就在工具描述里强调“当需要XX信息时，必须使用此工具”。

原因二：工具描述不够清晰。模型不知道这个工具能干什么，自然就不会用。把工具描述写具体，包含使用场景和参数说明。

原因三：模型能力不足。有些小模型对function calling的支持不好。换一个支持工具调用的模型试试。

5.2 工具调用参数错误怎么排查

参数错误的表现形式很多：参数名拼错、参数类型不对、缺少必填参数、多传了不存在的参数。排查步骤：

1. 打印模型返回的原始tool_calls，看参数到底是什么
2. 检查工具定义的parameters schema是否和实际函数签名一致
3. 在工具函数入口加参数校验，把错误信息返回给模型
4. 如果模型总是传错某个参数，在参数描述里加示例

# 参数校验示例 def search_web(query: str, max_results: int = 5): if not isinstance(query, str) or not query.strip(): return "错误：query必须是非空字符串" if not isinstance(max_results, int) or max_results < 1: max_results = 5 # 自动修正而不是报错 # ... 执行搜索

5.3 Agent陷入循环的破解方法

循环有两种：一种是重复调用同一个工具，另一种是在两个工具之间来回跳。破解方法：

• 调用记录去重：记录每次工具调用的名称和参数，如果重复就拒绝执行并提示模型
• 步数硬限制：设置max_steps，到了就强制停止
• 提示词加规则：明确告诉模型“不要重复调用相同参数的工具”
• 引入反思机制：每N步让模型总结一下当前进展，重新评估策略

5.4 任务成功率低的系统性优化

如果Agent跑十次只能成功三四次，说明系统还有优化空间。我一般从这几个方面入手：

优化提示词：加入更多示例，细化每一步的指引，明确输出格式。

优化工具：检查工具返回的信息是否足够模型做决策。很多时候模型做错决策是因为工具返回的信息不完整或有歧义。

优化任务拆解：把大任务拆成小任务，每个小任务单独跑Agent。小任务的成功率远高于大任务。

加入验证步骤：在关键步骤后加一个验证环节，让模型检查上一步的结果是否合理。这能拦截很多错误。

5.5 常见问题速查表

6. 从Demo到生产：还需要考虑什么

6.1 成本控制的实际经验

Agent的token消耗比普通对话高得多。一个复杂任务跑下来，可能消耗几万甚至几十万token。我实测过一个调研类任务，平均每次执行消耗约15000 token。如果每天跑100次，按中等价位模型算，一个月下来成本不小。

控制成本的手段：

• 缓存重复调用：相同参数的搜索工具调用，直接返回缓存结果
• 压缩上下文：及时清理不需要的历史消息
• 分级模型：简单决策用便宜模型，复杂推理用贵模型
• 限制步数：根据任务复杂度设置合理的max_steps

6.2 日志与可观测性

Agent跑在生产环境，你必须知道它每一步在干什么。我的做法是记录完整的执行轨迹：

import logging logging.basicConfig(level=logging.INFO) logger = logging.getLogger("agent") def log_step(step, action, detail): logger.info(f"[Step {step}] {action}: {detail}")

记录的内容包括：每步的输入输出、工具调用参数和结果、耗时、token消耗。这些数据不仅能帮你排查问题，还能用来分析Agent的行为模式，找到优化点。

6.3 安全边界设置

Agent能调工具、能执行代码，这意味着它有能力造成实际影响。必须设置安全边界：

• 工具白名单：只允许调用经过审核的工具
• 参数校验：对危险参数（如文件路径、命令内容）做严格校验
• 执行沙箱：代码执行类工具必须在隔离环境中运行
• 人工确认：高风险操作（如删除文件、发送请求）需要人工确认
• 审计日志：所有操作记录在案，可追溯

提示：永远不要给Agent无限制的文件系统访问权限。我一般只开放特定目录的读写权限，其他路径一律拒绝。

6.4 持续迭代的思路

Agent上线不是终点，而是起点。你需要持续收集失败案例，分析失败原因，然后针对性地优化。我的迭代节奏是：每周review一次失败案例，每月做一次系统性优化。

优化的优先级排序：先解决高频失败场景，再优化低频但影响大的场景，最后打磨体验细节。不要试图一次性解决所有问题，Agent的优化是一个长期过程。

7. 我个人的实操体会

跑通第一个Agent任务之后，我最大的感受是：Agent的能力上限不取决于模型，而取决于你的工程化水平。同样的模型，提示词写得好不好、工具设计得合不合理、错误处理到不到位，最终的任务成功率可能差好几倍。

另一个体会是：不要追求一步到位。我见过很多人一上来就想搭一个全能Agent，结果每个环节都做得不扎实，最后什么都跑不通。正确的做法是先跑通一个最简单的场景，比如“搜索→总结”，然后再逐步增加工具、优化提示词、加入记忆。每一步都验证通过再往下走。

还有一个很实用的经验：把Agent的每次执行都当成一次调试。不要只看最终结果对不对，要看它每一步的决策是否合理。有时候结果对了但过程是错的，这种“侥幸成功”在生产环境迟早会出问题。

最后分享一个我常用的调试技巧：把Agent的执行轨迹打印出来，用不同颜色标注模型的思考、工具调用和工具返回。这样一眼就能看出问题出在哪个环节。我用的是rich库，几行代码就能实现彩色输出，调试效率提升非常明显。

from rich.console import Console from rich.panel import Panel console = Console() def print_step(step_type, content): colors = {"think": "blue", "tool": "green", "result": "yellow", "error": "red"} console.print(Panel(content, title=step_type, border_style=colors.get(step_type, "white")))

这套东西跑通之后，你会发现Agent能做的事情远超预期。关键是迈出第一步，把最小闭环跑通，后面的优化都是在这个基础上做加法。