AI Agent开发实战：从核心架构到天气查询助手构建

在实际 AI 应用开发中，我们经常遇到一个核心矛盾：大模型本身知识渊博，但让它直接处理复杂、多步骤的任务时，往往表现得不尽如人意。比如，你无法直接要求一个基础大模型“帮我分析上个月的销售数据，生成一份PPT，并发送给市场部经理”。它可能会生成一段描述这个过程的文字，但无法真正执行。这就是Agent（智能体）技术要解决的核心问题。Agent 不是一个新的模型，而是一个赋予大模型“行动能力”的框架或系统，它让大模型能够理解任务、规划步骤、调用工具（如代码执行器、API、数据库）并最终完成目标。

对于开发者而言，从“调用大模型 API 生成文本”到“构建一个能自主完成任务的智能体”，中间存在巨大的认知和实践鸿沟。这涉及到对智能体架构、记忆、规划、工具使用等核心概念的理解，以及如何选择框架、编写技能（Skill）、处理异常等工程实践。本文旨在为你梳理一条清晰的 Agent 开发学习路径，从核心概念到环境搭建，再到一个可运行的最小案例，并深入探讨开发中的关键决策与常见陷阱。无论你是希望将 AI 能力集成到现有业务系统，还是探索下一代 AI 原生应用，掌握 Agent 开发都是不可或缺的一环。

1. 理解 Agent 的核心架构：从“思考”到“行动”

在深入代码之前，必须建立对 Agent 系统的基本认知。一个典型的 Agent 系统不是单一模块，而是一个由多个组件协同工作的架构。

1.1 Agent 是什么？超越聊天机器人的“执行者”

你可以将 Agent 理解为一个具备感知、规划、行动和反思能力的智能程序。其核心工作流通常遵循ReAct (Reasoning + Acting)范式：

1. 感知（Perception）：接收用户指令或环境信息。
2. 思考（Reasoning）：大模型（LLM）分析当前状态、历史记忆和可用工具，决定下一步该“想什么”或“做什么”。
3. 行动（Acting）：根据思考结果，执行具体操作，如调用一个工具函数、查询知识库或输出最终答案。
4. 观察（Observation）：获取行动的结果，并将其作为新的输入反馈给思考环节。 这个循环会持续进行，直到任务被判定为完成。

与传统的规则引擎或脚本相比，Agent 的“思考”环节由大模型驱动，使其能够处理开放域、非结构化的复杂任务。与仅用于对话的聊天机器人相比，Agent 的核心特征是拥有并能够调用外部工具（Tools）来影响现实世界或数字世界。

1.2 Agent 系统的关键组件

构建一个功能完整的 Agent，通常需要设计和集成以下组件：

• 大脑（Brain） - 大语言模型（LLM）：负责所有的推理、规划和决策。它是 Agent 的“思考”中心。你可以使用云端 API（如 OpenAI GPT-4, Claude, DeepSeek）或本地部署的模型（如 Ollama 管理的 Llama、Qwen 等）。
• 技能（Skills） / 工具（Tools）：这是 Agent 的“手”和“脚”。每个技能都是一个可执行的函数，封装了特定的能力。例如：
  • search_web(query): 执行网络搜索。
  • execute_python_code(code): 在安全沙箱中运行 Python 代码。
  • query_database(sql): 执行 SQL 查询。
  • send_email(to, subject, body): 发送邮件。 Agent 通过大模型决定在何时调用哪个工具，并生成符合工具输入要求的参数。
• 记忆（Memory）：让 Agent 拥有上下文感知能力。分为短期记忆（当前对话上下文）和长期记忆（向量数据库存储的历史交互、知识）。记忆使 Agent 能在多轮交互中保持一致性，并基于历史经验进行优化。
• 规划器（Planner）：对于复杂任务，Agent 需要将其分解为子任务。规划器负责制定或调整执行计划。有时这个功能直接由大模型承担，有时则由专门的模块处理。
• 执行器（Executor）：负责调度规划器产生的任务序列，调用相应的工具，并管理整个执行流程的状态。

1.3 主流 Agent 开发框架简介

为了高效开发，我们通常会借助现有的框架。以下是一些主流选择，各有侧重：

对于初学者和大多数应用场景，从LangChain入手是一个不错的选择，因为它提供了最全面的抽象和丰富的示例。

2. 环境准备与开发栈选择

在开始编写第一个 Agent 之前，需要搭建好开发环境并做出关键的技术选型。

2.1 基础环境配置

你需要准备以下基础环境：

1. Python 环境：推荐使用 Python 3.9 或以上版本。使用conda或venv创建独立的虚拟环境是绝对必要的，以避免包依赖冲突。

   # 使用 conda 创建环境 conda create -n ai-agent python=3.10 conda activate ai-agent # 或使用 venv python -m venv ai-agent # Windows ai-agent\Scripts\activate # Linux/Mac source ai-agent/bin/activate

2. 代码编辑器：VS Code 或 PyCharm 均可，确保安装好 Python 插件。
3. API 密钥：如果你计划使用 OpenAI、Anthropic 等云端模型，需要提前注册并获取相应的 API Key。请妥善保管，不要直接提交到代码仓库。

2.2 核心依赖安装

我们以 LangChain 为例，安装核心包。这里假设你使用 OpenAI 的模型。

pip install langchain langchain-openai langchain-community

• langchain: 核心框架。
• langchain-openai: OpenAI 模型的官方集成。
• langchain-community: 包含大量第三方工具和集成。

如果你需要与本地模型交互（例如通过 Ollama），则还需要安装：

pip install langchain-ollama

2.3 模型选择：云端 API 还是本地模型？

这是第一个关键决策点，取决于你的需求、预算和数据敏感性。

建议：在学习和原型开发阶段，优先使用云端 API（如 GPT-3.5-turbo），成本低且稳定。当进入涉及敏感数据的生产环境概念验证（PoC）时，再评估是否迁移到本地或私有化部署的模型。

3. 构建你的第一个 Agent：一个天气查询助手

让我们通过一个经典的“天气查询助手”案例，将理论付诸实践。这个 Agent 将能够理解用户关于天气的询问，并调用一个模拟的天气工具来获取信息。

3.1 项目结构与初始化

创建一个新的项目目录，结构如下：

weather_agent/ ├── tools/ │ └── weather_tool.py # 自定义天气工具 ├── agents/ │ └── weather_agent.py # Agent 定义与执行逻辑 ├── main.py # 程序入口 └── requirements.txt # 依赖列表

在requirements.txt中写入：

langchain langchain-openai python-dotenv

3.2 创建自定义工具（Skill）

工具是 Agent 能力的扩展。在tools/weather_tool.py中，我们定义一个简单的天气查询工具。在生产环境中，这里应该调用真实的天气 API（如 OpenWeatherMap）。

# tools/weather_tool.py from langchain.tools import tool from typing import Optional @tool def get_weather(city: str, date: Optional[str] = None) -> str: """ 根据城市名称（和可选日期）查询天气信息。 Args: city: 城市名称，例如“北京”、“Shanghai”。 date: 查询日期，格式为‘YYYY-MM-DD’。如果为None，则默认为今天。 Returns: 返回该城市的天气情况描述字符串。 """ # 这是一个模拟函数。真实场景应调用天气API。 # 例如：response = requests.get(f"https://api.weatherapi.com/...?q={city}&dt={date}") print(f"[工具调用] 正在查询{city}在{date if date else '今天'}的天气...") # 模拟一些逻辑 weather_conditions = ["晴", "多云", "阴", "小雨", "中雨", "大雪"] import random temperature = random.randint(-5, 35) condition = random.choice(weather_conditions) result = f"{city}在{date if date else '今天'}的天气是{condition}，气温大约{temperature}摄氏度。" return result

关键点解释：

1. @tool装饰器：这是 LangChain 提供的装饰器，它能自动将函数转化为 LangChain Agent 可以识别和调用的工具。
2. 类型提示（str,Optional[str]）：这非常重要！LangChain 会将函数的参数类型和文档字符串（"""）提供给大模型，帮助它理解如何调用这个工具。
3. 清晰的文档字符串：描述工具的功能、参数和返回值。这是大模型决定是否以及如何调用该工具的主要依据。

3.3 构建并运行 Agent

在agents/weather_agent.py中，我们创建 Agent 的核心逻辑。

# agents/weather_agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder from tools.weather_tool import get_weather # 1. 加载环境变量（从 .env 文件读取 API Key） load_dotenv() openai_api_key = os.getenv("OPENAI_API_KEY") if not openai_api_key: raise ValueError("请在 .env 文件中设置 OPENAI_API_KEY") # 2. 初始化大模型 # 使用 GPT-3.5-turbo，性价比高，适合演示 llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0, openai_api_key=openai_api_key) # temperature=0 使输出更确定，适合工具调用 # 3. 定义工具列表 tools = [get_weather] # 4. 构建提示词模板 # 这是指导 Agent 行为的关键。SystemMessage 设定角色和规则。 prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个专业的天气查询助手。请根据用户的问题，使用合适的工具获取天气信息。如果你没有合适的工具来回答问题，请如实告知用户。请用中文回复。"), MessagesPlaceholder(variable_name="chat_history"), # 预留位置给对话历史（记忆） ("human", "{input}"), # 用户输入 MessagesPlaceholder(variable_name="agent_scratchpad"), # 预留位置给 Agent 的思考过程 ]) # 5. 创建 Agent agent = create_openai_tools_agent(llm=llm, tools=tools, prompt=prompt) # 6. 创建 Agent 执行器 agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True) # verbose=True 会打印出 Agent 的思考过程，便于调试 # handle_parsing_errors=True 当模型输出无法解析为工具调用时，进行友好处理 def run_agent(query: str) -> str: """执行 Agent，处理用户查询""" try: result = agent_executor.invoke({"input": query, "chat_history": []}) return result["output"] except Exception as e: return f"Agent 执行出错: {e}" if __name__ == "__main__": # 简单测试 test_queries = [ "北京今天天气怎么样？", "帮我看看上海明天会不会下雨？", "旧金山下周一的天气呢？" ] for query in test_queries: print(f"\n用户: {query}") response = run_agent(query) print(f"助手: {response}")

在项目根目录创建.env文件，填入你的 OpenAI API Key：

OPENAI_API_KEY=sk-你的真实key

3.4 运行与验证

在项目根目录下运行：

python agents/weather_agent.py

你应该能看到类似以下的输出，其中verbose=True会展示 Agent 内部的思考链（Chain of Thought）：

用户: 北京今天天气怎么样？ > 进入新的 AgentExecutor 链... 我需要查询北京今天的天气，我有一个工具可以查询天气。 动作：get_weather 动作输入：{"city": "北京"} [工具调用] 正在查询北京在今天的天气... 观察：北京在今天天气是晴，气温大约22摄氏度。 思考：我已经获得了北京的天气信息。 最终答案：北京今天天气晴朗，气温大约22摄氏度。 > 链结束。 助手: 北京今天天气晴朗，气温大约22摄氏度。

这个输出清晰地展示了 ReAct 范式的过程：思考（需要查询天气） ->行动（调用get_weather工具） ->观察（工具返回结果） ->最终回答。

4. 深入 Agent 开发的关键议题与排错

完成第一个 Agent 后，你会遇到更复杂的需求和问题。以下是几个核心议题的深入探讨。

4.1 工具调用失败与参数解析错误

这是 Agent 开发中最常见的问题之一。现象是 Agent 决定调用工具，但调用时出错。

常见原因与排查：

1. 工具描述不清：模型的“思考”依赖于你为工具编写的文档字符串（Docstring）。确保描述准确、参数意义明确。
2. 参数类型不匹配：模型生成的参数格式可能不符合工具函数的要求。例如，工具期望date是字符串"2023-10-01"，但模型可能生成"明天"。
   • 解决方案：在工具函数内部增加参数清洗和验证逻辑。或者，使用 LangChain 的StructuredTool来定义更严格的参数模式（Pydantic Model）。
3. 模型“幻觉”调用不存在的工具：如果提示词中未清晰界定工具边界，模型可能会编造工具名。
   • 解决方案：在系统提示词中明确列出可用工具及其用途。使用create_openai_tools_agent这类 Agent 类型，它要求模型必须从提供的工具列表中选择。

改进的工具定义示例（使用 Pydantic 强化结构）：

from langchain.tools import StructuredTool from pydantic import BaseModel, Field class WeatherInput(BaseModel): city: str = Field(description="城市的中文或英文名称") date: str = Field(default="today", description="查询日期，格式为 YYYY-MM-DD 或 ‘today‘, ‘tomorrow‘") def get_weather_structured(city: str, date: str = "today") -> str: # ... 实现逻辑同上 ... return result weather_tool_structured = StructuredTool.from_function( func=get_weather_structured, name="get_weather", description="查询指定城市在指定日期的天气", args_schema=WeatherInput, # 关键：绑定严格的输入模式 return_direct=False, )

4.2 记忆（Memory）的实现

无状态的 Agent 无法进行多轮对话。我们需要为其添加记忆。LangChain 提供了多种记忆后端。

为天气助手添加对话记忆：

# agents/weather_agent_with_memory.py from langchain.memory import ConversationBufferMemory # 初始化记忆 memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True) # 在创建 AgentExecutor 时传入 memory agent_executor = AgentExecutor( agent=agent, tools=tools, verbose=True, memory=memory, # 关键：绑定记忆 handle_parsing_errors=True ) # 调用时不再需要手动传入空的 chat_history result = agent_executor.invoke({"input": query}) # memory 会自动管理 chat_history 的存储和注入

现在，当你连续问“北京天气如何？”和“那上海呢？”，Agent 能理解“那上海呢？”指的是天气查询。

4.3 处理复杂任务与规划

对于“帮我对比北京和上海未来三天的天气”这类任务，简单的单步工具调用不够。你需要更强大的规划能力。

方案一：使用 LangChain 的 Plan-and-Execute 模式。这需要一个“规划者”LLM 先制定计划，再由“执行者”LLM 按计划调用工具。方案二：使用 LangGraph。它允许你以图（Graph）的形式定义工作流，明确节点（工具/LLM调用）和边（执行路径），非常适合复杂、有状态的流程。

简单示例：使用 LangGraph 编排多城市查询

# 注：这是一个概念性简化示例，实际 LangGraph 代码更详细 from langgraph.graph import StateGraph, END from typing import TypedDict, List import operator class AgentState(TypedDict): cities: List[str] weather_results: List[str] final_answer: str def plan_step(state: AgentState): """规划节点：解析用户输入，提取要查询的城市列表""" # 这里可以调用一个 LLM 来解析用户意图 # 假设我们简单地从输入中提取 state["cities"] = ["北京", "上海"] # 模拟解析结果 return state def query_weather_node(state: AgentState): """执行节点：并发或顺序查询每个城市的天气""" for city in state["cities"]: weather = get_weather(city) # 调用工具 state["weather_results"].append(weather) return state def synthesize_step(state: AgentState): """合成节点：汇总所有结果，生成最终答案""" all_results = "\n".join(state["weather_results"]) state["final_answer"] = f"对比结果如下：\n{all_results}" return state # 构建图 workflow = StateGraph(AgentState) workflow.add_node("planner", plan_step) workflow.add_node("querier", query_weather_node) workflow.add_node("synthesizer", synthesize_step) workflow.set_entry_point("planner") workflow.add_edge("planner", "querier") workflow.add_edge("querier", "synthesizer") workflow.add_edge("synthesizer", END) app = workflow.compile() # 运行这个图 result = app.invoke({"cities": [], "weather_results": [], "final_answer": ""})

4.4 生产环境考量

当 Agent 从演示走向生产，必须考虑以下问题：

1. 稳定性与容错：

   • 工具调用超时与重试：网络请求可能失败。为工具调用添加重试机制和超时设置。
   • LLM 调用限流与降级：监控 API 调用频率，准备备用模型（如从 GPT-4 降级到 GPT-3.5）。
   • 输入输出过滤：对用户输入和模型输出进行安全检查，防止提示词注入或生成有害内容。

2. 可观测性：

   • 全链路日志：记录每一次 LLM 调用（输入/输出）、工具调用（参数/结果）、Agent 的中间步骤。这对于调试和优化至关重要。
   • 链路追踪（Tracing）：使用 LangSmith 或 OpenTelemetry 等工具，可视化 Agent 的执行轨迹，分析耗时和成本。

3. 成本控制：

   • 缓存：对相同的 LLM 请求或工具查询结果进行缓存，减少重复调用。
   • Token 计数：估算每次交互的 token 消耗，设置预算和警报。

4. 安全：

   • 工具权限控制：不是所有工具都应对所有用户开放。根据用户身份或上下文动态提供工具列表。
   • 沙箱环境：对于执行代码（如execute_python_code）这类高危工具，必须在严格的沙箱环境中运行。

5. 最佳实践与进阶学习路线

5.1 Agent 开发清单

在将一个 Agent 投入生产前，请对照此清单进行检查：

• [ ]工具设计：每个工具是否有清晰、单一的责任？文档字符串是否准确描述了功能、参数和返回值？
• [ ]提示词工程：系统提示词是否明确设定了 Agent 的角色、规则和可用工具？是否限制了其行为范围？
• [ ]错误处理：是否处理了 LLM 输出解析失败、工具调用异常、网络超时等情况？
• [ ]记忆管理：是否选择了合适的记忆类型（缓冲、窗口、摘要）？记忆长度是否合理，避免上下文过长？
• [ ]可观测性：是否记录了关键步骤的日志？是否有办法追踪一次用户请求的完整执行链？
• [ ]性能：是否对耗时长的工具调用做了异步处理？是否有缓存策略？
• [ ]安全：用户输入是否经过清洗？工具调用是否有权限校验？执行代码是否在沙箱中？

5.2 常见陷阱（坑）

1. 过度依赖 Agent 处理一切：并非所有任务都需要 Agent。简单的分类、提取任务用传统的函数或 RAG 可能更高效、更稳定。Agent 适用于需要多步骤推理和外部交互的复杂任务。
2. 提示词过于冗长或模糊：提示词质量直接决定 Agent 表现。避免写小说，要清晰、简洁、结构化。明确给出“如果做不到 X，就做 Y”的兜底指令。
3. 忽视工具调用的可靠性：工具是 Agent 与真实世界交互的桥梁。工具本身的稳定性、错误处理和接口设计比 Agent 框架的选择更重要。
4. 无限循环或昂贵调用：Agent 可能在规划中陷入死循环，或反复调用高成本工具（如网络搜索）。需要在系统层面设置最大迭代次数和成本监控。

5.3 进阶学习方向

掌握了单 Agent 开发后，你可以探索更前沿的领域：

1. 多智能体（Multi-Agent）系统：让多个具有不同角色（分析师、执行者、评审员）的 Agent 协作解决问题。研究AutoGen和CrewAI框架。
2. 智能体与 RAG 深度结合：让 Agent 不仅能调用工具，还能从庞大的私有知识库中精准检索信息。深入研究LlamaIndex的 Agent 能力。
3. 智能体模拟与评估：如何定量评估一个 Agent 的性能？如何构建测试场景（Simulation）来批量测试其可靠性和有效性？
4. 长上下文与记忆优化：当对话或任务历史很长时，如何高效地利用记忆？研究记忆压缩、总结和向量检索等技术。
5. 强化学习与智能体优化：让 Agent 能从与环境的交互中学习，优化其决策策略。

学习 Agent 开发是一个从“知其然”到“知其所以然”的过程。从使用高级框架封装好的 Agent 开始，快速体验其能力；然后深入理解其组成模块（模型、提示词、工具、记忆），并学会自定义；最后挑战复杂的工作流编排和多智能体协作。始终以解决实际问题为导向，先构建一个最小可行产品（MVP），再根据反馈和需求迭代优化，这是掌握这项技术最有效的路径。