企业官网建设流程全解析

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度

在实际项目中，AI Agent 已经从实验室概念演变为解决复杂任务的关键技术组件。无论是自动化客服、智能数据分析助手，还是集成在应用中的个性化推荐引擎，其核心都是让机器能够理解目标、规划步骤、调用工具并执行决策。对于开发者而言，从零开始构建一个可用的 Agent 往往面临概念庞杂、工具链不熟悉、代码与理论脱节等挑战。本文旨在提供一个结构清晰、可动手实践的 AI Agent 开发入门指南，帮助具备基础编程能力的开发者，理解 Agent 的核心工作机制，并完成一个具备规划与执行能力的简单任务执行 Agent。

我们将从最基础的 Agent 概念和工作流讲起，然后搭建一个最小化的开发环境，接着通过一个“联网信息查询与总结”的完整案例，展示如何利用主流框架（如 LangChain）的关键组件构建 Agent。文章会详细解释每一步的代码意图、配置参数以及背后的设计逻辑，并提供运行验证、常见问题排查路径和向更复杂场景扩展的建议。学完后，你将能够掌握 Agent 开发的基本模式，并具备将其应用于实际业务场景的初步能力。

1. 理解 AI Agent 的核心：从感知到行动的循环

在深入代码之前，必须厘清 AI Agent 与普通调用大语言模型（LLM）API 的程序有何本质区别。很多初学者误以为给 LLM 加个循环就是 Agent，这忽略了其核心的自主决策与工具使用能力。

1.1 Agent 是什么：超越简单问答的智能体

通俗地讲，一个 AI Agent 是一个能够感知环境、自主决策并执行行动以达成给定目标的软件实体。它不仅仅是根据输入生成文本，而是具备“思考-行动-观察”的循环能力。例如，一个简单的“天气查询Agent”的思考过程可能是：用户目标是“北京明天适合穿什么？”，Agent 需要先规划步骤：1. 获取北京明天的天气预报。2. 根据天气数据（温度、降水）生成穿衣建议。3. 将建议返回给用户。其中，第一步就需要调用一个“获取天气”的工具（Tool）。

技术定义上，一个典型的 Agent 系统包含几个核心组件：

• 规划器（Planner）：通常由 LLM 担任，负责将复杂目标分解为可执行的步骤或子任务序列。
• 工具（Tools）：Agent 可以调用的外部函数或 API，用于获取信息（如搜索、查数据库）或执行操作（如发送邮件、操作文件）。
• 记忆（Memory）：用于存储和回顾与当前任务相关的历史信息（对话历史、中间结果），为后续决策提供上下文。
• 执行器（Executor）：协调整个循环，根据规划调用工具，处理工具返回的结果，并决定下一步是继续规划、重新规划还是结束任务。

1.2 Agent 的典型工作流：ReAct 模式

目前最流行且有效的 Agent 工作流之一是ReAct (Reasoning + Acting)模式。它清晰地展示了 Agent 的思考过程。

1. 思考（Think）：LLM 根据当前目标、历史记录和可用工具列表，分析下一步应该做什么。输出格式通常是：“我需要先使用 X 工具来获取 Y 信息。”
2. 行动（Act）：根据思考结果，调用指定的工具，并传入相应的参数。
3. 观察（Observe）：获取工具执行后的返回结果（可能是数据，也可能是成功/失败状态）。
4. 循环：将“思考-行动-观察”的结果作为新的上下文，再次送入 LLM 进行下一轮思考，直到 LLM 认为任务已完成并输出最终答案。

这个循环的关键在于，LLM 的每次“思考”都基于最新的环境观察（工具执行结果），从而能够动态调整计划。例如，如果调用天气 API 失败，LLM 可能会思考：“天气 API 调用失败，我可以尝试使用网络搜索工具来查找天气信息。”

1.3 为什么需要框架：LangChain 的角色

手动实现上述循环、工具调用封装、提示词（Prompt）管理和记忆存储非常繁琐且容易出错。因此，我们使用LangChain这样的框架。它抽象了这些通用模式，提供了构建 Agent 所需的高层组件，让我们可以更专注于业务逻辑和工具定义，而不是底层通信和状态管理。

在接下来的部分，我们将基于 LangChain 来构建我们的第一个 Agent。

2. 环境准备与依赖配置：搭建可复现的开发底座

一个稳定、版本对齐的开发环境是后续所有步骤的基础。Agent 开发涉及 LLM 服务、Python 环境、框架和多个工具库，版本冲突是新手最常见的“拦路虎”。

2.1 基础环境与 Python 版本

建议使用 Python 3.9 至 3.11 的稳定版本。Python 3.12 及以上版本可能存在某些依赖库的兼容性问题。使用虚拟环境（venv 或 conda）隔离项目依赖是必须遵循的最佳实践。

# 创建并激活虚拟环境 (以 venv 为例) python -m venv .venv # Windows .venv\Scripts\activate # Linux/macOS source .venv/bin/activate

激活虚拟环境后，命令行提示符前通常会出现环境名（如(.venv)），这表示后续的 pip 安装都会作用于该独立环境。

2.2 核心依赖安装

我们将使用 LangChain 作为主要框架，并选择 OpenAI 的 GPT 模型作为 LLM 驱动（你也可以替换为其他兼容 API 的模型）。此外，为了演示工具调用，我们需要一个执行网络搜索的工具。这里使用 DuckDuckGo 搜索（无需 API Key）作为示例。

创建requirements.txt文件，内容如下：

langchain==0.1.0 langchain-openai==0.0.5 langchain-community==0.0.10 duckduckgo-search==5.4.0 python-dotenv==1.0.0

逐行解释：

• langchain: LangChain 核心框架。
• langchain-openai: LangChain 对 OpenAI 模型的官方集成。
• langchain-community: 社区维护的各种工具、组件和集成。
• duckduckgo-search: 提供 DuckDuckGo 搜索功能的 Python 库，我们将用它构建一个搜索工具。
• python-dotenv: 用于从.env文件加载环境变量（如 API Key），避免将敏感信息硬编码在代码中。

使用 pip 安装所有依赖：

pip install -r requirements.txt

注意：依赖版本号是动态变化的。上述版本在撰写时能保证兼容性。如果未来遇到问题，可以尝试移除版本号（pip install langchain）安装最新版，但需注意 API 可能发生变更。

2.3 配置 LLM 服务与 API Key

你需要一个可用的 LLM API。这里以 OpenAI 为例。访问 OpenAI 平台创建 API Key。切勿将 API Key 直接提交到代码仓库。

在项目根目录创建.env文件：

OPENAI_API_KEY=你的实际API密钥 OPENAI_BASE_URL=https://api.openai.com/v1 # 如果你使用官方服务，此项可选。若使用代理或兼容服务，需修改。

在代码中，使用python-dotenv加载这个 Key：

from dotenv import load_dotenv load_dotenv() # 这会从 .env 文件加载环境变量到 os.environ # 现在可以通过 os.getenv('OPENAI_API_KEY') 获取密钥

3. 构建第一个任务执行 Agent：联网查询与总结

我们将构建一个能够根据用户问题，自动决定是否需要联网搜索，并整合信息给出答案的 Agent。这个例子涵盖了 Agent 的核心要素：LLM 驱动、工具定义、流程控制。

3.1 项目结构与初始化

创建一个名为simple_agent.py的文件。首先导入必要的模块并初始化 LLM。

import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain.prompts import PromptTemplate from langchain_community.utilities import DuckDuckGoSearchAPIWrapper # 1. 加载环境变量 load_dotenv() # 2. 初始化 LLM # 使用 gpt-3.5-turbo 模型，温度设为 0 使其输出更确定。根据你的 API 配置，可能需要调整 base_url。 llm = ChatOpenAI( model="gpt-3.5-turbo", temperature=0, api_key=os.getenv("OPENAI_API_KEY"), # base_url=os.getenv("OPENAI_BASE_URL") # 如果使用非官方端点，取消注释并设置 )

关键参数解释：

• model: 指定使用的模型。gpt-3.5-turbo性价比高，适合学习和简单任务。对于复杂推理，可升级到gpt-4。
• temperature: 控制输出的随机性。范围 0~2，值越低输出越确定和一致。在 Agent 场景下，通常设为 0 或较低值，以保证规划的逻辑稳定性。
• api_key: 从环境变量中读取，保证安全。

3.2 定义工具：赋予 Agent “手脚”

工具是 Agent 与外部世界交互的桥梁。这里我们定义一个网络搜索工具。

# 3. 定义工具 # 使用 DuckDuckGo 搜索包装器 search = DuckDuckGoSearchAPIWrapper() def search_tool(query: str) -> str: """ 执行网络搜索并返回摘要结果。 参数 query: 搜索查询字符串。 返回: 搜索结果的前几条摘要文本。 """ # 限制返回结果数量，避免上下文过长 return search.run(query, max_results=3) # 将函数封装成 LangChain Tool 对象 tools = [ Tool( name="Search", func=search_tool, description="""当你需要回答关于实时信息、最新事件、特定事实或未知领域的问题时，使用此工具。 输入应该是一个具体的搜索查询字符串。""" ), ]

工具定义详解：

• name: 工具的唯一标识符，LLM 在思考时会根据这个名字来决定调用哪个工具。
• func: 工具对应的 Python 可调用对象（函数）。
• description:这是最重要的部分。LLM 根据描述来判断在什么情况下使用该工具。描述必须清晰、具体，说明工具的用途和输入格式。模糊的描述会导致 LLM 误用或不用工具。
• 在search_tool函数中，我们通过max_results限制返回条目，防止过多的搜索结果挤占 LLM 的上下文窗口（Token 有限）。

3.3 构建 ReAct Agent 与执行器

LangChain 提供了高阶的create_react_agent函数，它已经内置了 ReAct 模式的提示词模板和解析逻辑。我们需要提供 LLM、工具列表和一个提示词（Prompt）。

# 4. 创建 ReAct Agent # 首先，定义系统提示词，用于设定 Agent 的角色和行为准则 system_prompt = """你是一个有帮助的AI助手。你可以使用工具来获取信息。 请遵循以下步骤： 1. 思考：分析用户的问题，判断是否需要使用工具，以及使用哪个工具。 2. 行动：如果需要工具，就调用合适的工具。工具调用格式为：`Action: <工具名>\\nAction Input: <输入>` 3. 观察：你会收到工具返回的结果。 4. 重复思考、行动、观察，直到你拥有足够的信息来回答问题。 5. 最终答案：基于所有观察，给出清晰、准确的最终答案。 你有以下工具可用： {tools} 开始！记住，如果你不需要工具，就直接给出答案。 问题：{input} 思考：""" prompt = PromptTemplate.from_template(system_prompt) # 使用 create_react_agent 创建 Agent agent = create_react_agent(llm, tools, prompt) # 5. 创建 Agent 执行器 agent_executor = AgentExecutor( agent=agent, tools=tools, verbose=True, # 设为 True 可以看到 Agent 的思考过程，调试时非常有用 handle_parsing_errors=True, # 处理 LLM 输出格式解析错误 max_iterations=5, # 限制最大迭代次数，防止无限循环 early_stopping_method="generate", # 当 LLM 输出最终答案时停止 )

关键配置解释：

• verbose=True: 强烈建议在开发阶段开启。它会在控制台打印出 Agent 完整的“思考（Thought）”、“行动（Action）”、“观察（Observation）”日志，是理解和调试 Agent 行为的关键。
• handle_parsing_errors=True: LLM 的输出可能偶尔不符合框架预期的解析格式（如缺少Action:关键字）。此参数允许执行器尝试从错误中恢复，而不是直接崩溃。
• max_iterations=5:安全护栏。防止因逻辑错误或工具失败导致 Agent 陷入死循环，不断消耗 API 调用和 Token。
• early_stopping_method=”generate”: 当 LLM 的输出被识别为“最终答案”时（即不再包含工具调用），自动停止循环。

3.4 运行与验证：观察 Agent 的思考过程

现在，让我们用几个不同的问题来测试我们的 Agent。

# 6. 运行 Agent 进行测试 if __name__ == "__main__": test_questions = [ "什么是人工智能？", # 知识型问题，可能无需搜索 "截至今天，苹果公司（AAPL）的股价是多少？", # 实时信息，需要搜索 "请总结一下昨天关于火星探测的主要新闻。", # 复杂任务，需要搜索并总结 ] for question in test_questions: print(f"\n{'='*50}") print(f"问题: {question}") print(f"{'='*50}") try: result = agent_executor.invoke({"input": question}) print(f"\n最终答案: {result['output']}") except Exception as e: print(f"执行出错: {e}")

运行脚本：python simple_agent.py。由于设置了verbose=True，你将在控制台看到类似以下的输出（内容为示例）：

================================================== 问题: 截至今天，苹果公司（AAPL）的股价是多少？ ================================================== 思考：用户想知道苹果公司今天的股价，这是实时金融信息，我无法从内部知识直接获取，需要使用搜索工具。 Action: Search Action Input: AAPL stock price today Observation：苹果(AAPL)股价今日开盘为...当前价格为 182.63 美元，上涨 0.5%...（实际搜索返回的文本） 思考：我已经获得了苹果公司今天的股价信息，可以给出答案了。 最终答案：根据最新信息，苹果公司（AAPL）的股价今天目前约为 182.63 美元。 最终答案: 根据最新信息，苹果公司（AAPL）的股价今天目前约为 182.63 美元。

结果分析：

1. 对于“什么是人工智能？”，Agent 可能直接利用 LLM 的内部知识回答，不调用工具。
2. 对于股价问题，Agent 识别出需要实时数据，正确调用了Search工具，并生成了查询”AAPL stock price today“。
3. 对于火星新闻，Agent 可能会先搜索，然后对返回的多条结果进行总结归纳。

通过这个流程，你已经完成了一个具备基础规划与工具调用能力的 AI Agent。

4. 核心机制详解与参数调优

仅仅让 Agent 跑起来还不够，理解其内部机制和关键参数，才能有效诊断问题和优化性能。

4.1 提示词（Prompt）的设计艺术

Prompt 是引导 LLM 扮演好“规划者”角色的关键。一个糟糕的 Prompt 会导致 Agent 行为混乱。我们的系统提示词包含了几个关键部分：

• 角色设定：你是一个有帮助的AI助手。这设定了基本的交互基调。
• 流程指令：明确列出了“思考-行动-观察”的步骤，并给出了工具调用的格式范例（Action: ...）。ReAct 框架依赖这种固定格式来解析 LLM 的输出。
• 工具描述：{tools}是一个占位符，运行时会被替换为所有工具的name和description。清晰的工具描述是 LLM 正确选择工具的前提。
• 问题上下文：{input}是用户问题的占位符。
• 结束指令：记住，如果你不需要工具，就直接给出答案。这防止了 LLM 对所有问题都机械地尝试使用工具。

优化建议：

• 如果 Agent 频繁错误调用工具，可以强化工具描述的区分度。
• 如果 Agent 在应该结束时继续循环，可以在 Prompt 中更强调“当你拥有足够信息时，给出最终答案”。
• 对于复杂任务，可以在 Prompt 中加入“分步解决”、“先理解核心问题”等引导词。

4.2 Agent 执行器的关键参数

AgentExecutor的参数直接影响 Agent 的稳定性、成本和性能。

4.3 工具（Tools）的扩展与封装

除了搜索，Agent 可以拥有任何你能用代码实现的工具。以下是几种常见工具类型及其实现思路：

1. 计算器/单位转换：封装eval（需极度谨慎）或sympy库。
2. 数据库查询：封装 SQLAlchemy 或特定数据库驱动，执行查询并返回格式化结果。
3. API 调用：封装requests库，调用外部 RESTful API（如天气、股票、翻译）。
4. 文件操作：封装读写本地文件或云存储的操作。
5. 代码执行：封装一个安全的沙箱环境来运行代码（风险高，需严格隔离）。

定义新工具的示例（模拟一个计算器）：

from langchain.tools import Tool import re def safe_calculator(expression: str) -> str: """执行安全的数学表达式计算。只支持数字和基础运算符。""" # 简单的安全过滤，防止代码注入 if not re.match(r'^[\d\s\+\-\*\/\(\)\.]+$', expression): return "错误：表达式包含不安全字符。" try: # 警告：实际生产环境应使用更安全的评估方式，如 ast.literal_eval 或专用库 result = eval(expression) return f"计算结果: {result}" except Exception as e: return f"计算错误: {e}" calculator_tool = Tool( name="Calculator", func=safe_calculator, description="用于执行数学计算。输入是一个纯数学表达式，例如 '（12 + 5） * 2'。不要包含任何文字。" ) # 将新工具加入到 tools 列表中 tools.append(calculator_tool)

重要安全警告：上例中的eval仅用于演示，在生产环境中直接使用eval处理用户输入是极其危险的，会导致代码注入漏洞。必须使用更安全的替代方案，如ast.literal_eval（限制更多）或numexpr等库。

5. 常见问题排查与调试指南

在开发 Agent 时，你会遇到一些典型问题。以下是排查路径和解决方案。

5.1 Agent 不调用工具，直接回答问题

现象：对于明显需要实时信息的问题（如“现在几点了？”），Agent 却基于 LLM 的旧知识编造了一个答案。

可能原因与排查：

1. 工具描述不清晰：检查工具的description是否准确说明了使用场景（如“获取实时信息”）。LLM 可能不理解何时该用它。
   • 解决：重写描述，使其更具体、更具场景化。例如：“当问题涉及当前时间、实时股价、最新新闻等非静态知识时使用此工具。”
2. Prompt 引导不足：系统 Prompt 可能没有强调查询实时信息时必须使用工具。
   • 解决：在 Prompt 中明确加入规则，例如：“对于涉及今天、现在、最新、当前等时间关键词的问题，你必须优先使用搜索工具确认信息。”
3. LLM 温度（Temperature）过高：温度值过高导致输出随机性大，可能忽略了工具调用指令。
   • 解决：将temperature设为 0 或一个较低的值（如 0.1）。

5.2 Agent 陷入无限循环或达到最大迭代次数

现象：控制台不断打印思考、行动、观察的日志，始终不输出最终答案，直到被max_iterations强制停止。

可能原因与排查：

1. 工具返回结果质量差：工具返回的内容可能无法回答子问题，导致 LLM 认为信息不足，反复调用同一个或不同的工具。
   • 解决：检查工具函数。对于搜索工具，可以优化查询词或对返回结果进行清洗和摘要。添加日志打印工具的输入和原始输出。
2. 任务过于复杂或模糊：LLM 无法将模糊的目标分解为清晰的步骤。
   • 解决：让用户提供更具体的问题。或者在 Prompt 中引导 LLM 进行更精细的步骤分解，例如：“请将复杂任务分解为不超过3个明确的子问题。”
3. 上下文混乱：随着迭代进行，大量的“思考”和“观察”文本积累在上下文中，干扰了 LLM 的最新决策。
   • 解决：这是复杂 Agent 系统的常见挑战。可以考虑使用ConversationSummaryMemory或ConversationBufferWindowMemory来管理历史长度，只保留最近的几次交互。

5.3 工具调用格式解析错误

现象：控制台抛出类似OutputParserException的错误，提示无法解析 LLM 的输出。

可能原因与排查：

1. LLM 没有遵循指令格式：LLM 的输出没有严格按照Action: ...的格式。
   • 解决：首先检查verbose日志，看 LLM 输出了什么。强化 Prompt 中的格式指令，使用更明确的示例（Few-Shot Prompting）。例如，在 Prompt 中加入：

     示例： 问题：纽约现在的天气如何？ 思考：这是一个关于实时天气的问题，我需要使用搜索工具。 Action: Search Action Input: New York current weather

2. 中文或其他语言导致的格式偏差：LLM 可能用中文输出了“动作：搜索”。
   • 解决：在 Prompt 中严格要求使用英文关键词Action和Action Input，或者将整个 Agent 的交互语言设置为英文。

5.4 性能与成本优化

问题：每次运行都消耗大量 Token，响应慢，API 调用费用高。

优化策略：

1. 精简 Prompt：移除 Prompt 中不必要的叙述性文字。
2. 限制工具返回长度：像我们之前做的，在search_tool中使用max_results。对于其他工具，也要限制返回数据的大小，只提取关键信息。
3. 使用更便宜的模型：对于规划步骤，可以尝试使用gpt-3.5-turbo；对于需要高质量总结或创作的最终答案生成，再使用gpt-4。这需要更复杂的 Agent 架构。
4. 实现缓存：对于相同的问题或工具查询，可以使用langchain.cache（如SQLiteCache）缓存 LLM 响应和工具结果，显著提升重复请求的速度并降低成本。

6. 从原型到生产：最佳实践与扩展方向

让一个演示 Agent 稳定运行于生产环境，还需要考虑更多因素。

6.1 生产环境检查清单

在部署前，请对照此清单进行检查：

• [ ]安全性：
  • API Keys、数据库密码等敏感信息是否已通过环境变量或密钥管理服务管理？
  • 工具函数（如计算器）是否进行了输入验证和安全过滤，防止注入攻击？
  • Agent 的输入是否进行了内容安全过滤？
• [ ]可靠性：
  • 是否设置了合理的max_iterations和max_execution_time？
  • 是否对工具调用和 LLM 调用添加了重试机制和超时处理？
  • 是否有降级方案？例如，当核心工具失败时，Agent 能否给出友好的错误提示或转向备用方案？
• [ ]可观测性：
  • 是否记录了完整的 Agent 执行日志（包括思考过程、工具调用及结果）？这对于排查问题和优化 Prompt 至关重要。
  • 是否监控了 Token 消耗、响应延迟和错误率？
• [ ]性能：
  • 是否对频繁查询实施了缓存？
  • 对于耗时长的工具调用，是否考虑使用异步（Async）模式？

6.2 扩展方向：构建更强大的 Agent

掌握了基础模式后，你可以探索以下方向来增强你的 Agent：

1. 多工具协同：为 Agent 装备更多工具，如数据库查询、邮件发送、数据分析等，使其能处理跨领域工作流。
2. 记忆（Memory）集成：让 Agent 记住对话历史或任务上下文。LangChain 提供了多种 Memory 类型：
   • ConversationBufferMemory: 保存所有历史消息。
   • ConversationSummaryMemory: 对长历史进行摘要，节省 Token。
   • VectorStoreRetrieverMemory: 将历史存入向量数据库，实现基于语义的相关信息检索。
3. 智能路由（Router）：根据用户输入的意图，自动选择不同的子 Agent 或处理链。例如，将“订机票”路由到旅行 Agent，将“分析报表”路由到数据分析 Agent。
4. 自主智能体（Autonomous Agent）：如 AutoGPT 模式，给 Agent 一个长期目标（如“研究某个主题并写份报告”），它能够自主创建任务列表、优先排序并执行，直至目标达成。这需要更复杂的任务规划、优先级管理和自我反思机制。
5. 与现有系统集成：将 Agent 作为微服务嵌入到你现有的业务系统中，通过 API 提供智能决策支持。

6.3 框架选型考量

虽然本文以 LangChain 为例，但生态中还有其他优秀框架，如Semantic Kernel(微软)、LlamaIndex(更专注于数据索引与检索)。选择时考虑：

• LangChain：生态最丰富，组件齐全，社区活跃，学习资料多，是快速上手的首选。
• Semantic Kernel：与 .NET 生态结合紧密，规划（Planner）功能强大，适合企业级复杂工作流。
• LlamaIndex：如果你的核心需求是让 Agent 基于私有知识库（文档、数据库）进行问答，LlamaIndex 的数据连接和检索能力是强项。

建议从 LangChain 开始建立对 Agent 的完整认知，再根据项目特定需求评估其他框架。

构建 AI Agent 是一个迭代过程，核心在于清晰定义任务边界、精心设计工具、不断调试 Prompt 并建立有效的安全护栏。从本文这个可运行的简单搜索 Agent 出发，你已经掌握了最核心的循环机制和调试方法，接下来就是结合具体业务场景，不断实践和深化的过程。

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度