手把手搭建你的第一个Agent：用LangChain 10分钟跑通"会说话的助手" 💻

导读：前三期我们把理论吃透了，今天终于要动手写代码了！🎉 本文将手把手带你用LangChain搭建一个真正能跑的AI Agent——一个能搜索、能计算、能聊天的智能助手。跟着做，10分钟出结果！

---

一、今天的目标 🎯

我们要搭建一个这样的Agent：

能力	示例
💬 自然对话	“你好，请介绍一下自己”
🔍 联网搜索	“今天有什么科技新闻？”
🧮 精确计算	“如果每月存5000，年化5%，10年后有多少钱？”
📅 日期查询	“今天星期几？下个节假日是什么时候？”

架构图

---

二、环境准备 🛠️

2.1 安装依赖

# 使用pip安装核心依赖
pip install langchain langchain-openai langgraph

2.2 配置API Key

import os

# 设置OpenAI API Key（也可以用其他模型的API）
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# 如果使用其他模型，设置对应的base_url
# os.environ["OPENAI_API_BASE"] = "https://your-api-base.com/v1"

2.3 依赖清单表

依赖包	版本	用途
langchain	>=0.3	Agent框架核心
langchain-openai	>=0.2	OpenAI模型接入
langgraph	>=1.0	Agent状态管理与编排

---

三、第一步：定义工具 🔧

Agent的能力来自工具。我们先定义三个实用工具：

from langchain.tools import tool
import json
from datetime import datetime, timedelta

# ========== 工具1：网络搜索 ==========
@tool
def web_search(query: str) -> str:
    """搜索互联网获取最新信息。当用户询问最新新闻、实时数据或不确定的事实时使用此工具。
    
    Args:
        query: 搜索关键词，建议使用简洁的中文或英文关键词
    """
    # 这里使用Tavily搜索API（需要注册获取API Key）
    # 实际项目中可以替换为其他搜索引擎
    from langchain_community.tools.tavily_search import TavilySearchResults
    search = TavilySearchResults(max_results=3)
    results = search.invoke(query)
    return "\n".join([f"• {r['content']}" for r in results])


# ========== 工具2：数学计算 ==========
@tool  
def calculator(expression: str) -> str:
    """执行数学计算。当用户需要进行数学运算、财务计算、单位换算等时使用此工具。
    
    Args:
        expression: 数学表达式，如 '2**10' 或 '100 * 1.05**10'
    """
    try:
        # 安全地计算数学表达式
        allowed_chars = set("0123456789+-*/.() %^")
        if not all(c in allowed_chars or c.isalpha() for c in expression):
            return "错误：表达式包含不允许的字符"
        result = eval(expression, {"__builtins__": {}}, {})
        return f"计算结果：{expression} = {result}"
    except Exception as e:
        return f"计算错误：{str(e)}"


# ========== 工具3：日期查询 ==========
@tool
def date_query(action: str) -> str:
    """查询日期和时间相关信息。当用户询问今天日期、星期几、节假日等时使用。
    
    Args:
        action: 查询类型，支持 'today'(今天日期), 'weekday'(星期几), 'next_holiday'(下个节假日)
    """
    today = datetime.now()
    
    if action == "today":
        return f"今天是 {today.strftime('%Y年%m月%d日')}，{today.strftime('%A')}"
    
    elif action == "weekday":
        weekdays = ["星期一", "星期二", "星期三", "星期四", "星期五", "星期六", "星期日"]
        return f"今天是 {weekdays[today.weekday()]}"
    
    elif action == "next_holiday":
        # 简化版：计算距离下一个假期的天数
        holidays = {
            "劳动节": datetime(today.year, 5, 1),
            "国庆节": datetime(today.year, 10, 1),
            "元旦": datetime(today.year + 1, 1, 1),
        }
        future_holidays = {k: v for k, v in holidays.items() if v > today}
        if future_holidays:
            next_h = min(future_holidays.items(), key=lambda x: x[1])
            days = (next_h[1] - today).days
            return f"距离{next_h[0]}还有 {days} 天（{next_h[1].strftime('%Y年%m月%d日')}）"
        return "暂无节假日信息"
    
    return "不支持的查询类型"

⭐ 重点注意：工具的**docstring（函数注释）**非常重要！Agent是通过阅读docstring来决定什么时候用哪个工具的。写得好，Agent就聪明；写得差，Agent就犯傻。

---

四、第二步：创建Agent 🤖

工具定义好了，接下来创建Agent：

from langchain.agents import create_react_agent
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# 1. 初始化大模型（Agent的"大脑"）
llm = ChatOpenAI(
    model="gpt-4o",
    temperature=0.7,
)

# 2. 注册所有工具
tools = [web_search, calculator, date_query]

# 3. 定义系统提示词（Agent的"性格"）
system_prompt = """你是一个 helpful 的AI助手，名叫"小智"。

你有以下能力：
- 🔍 联网搜索：获取最新信息
- 🧮 数学计算：精确计算各种数学问题
- 📅 日期查询：查询日期和节假日信息

工作原则：
1. 需要最新信息时，使用搜索工具
2. 需要精确计算时，使用计算器（不要心算！）
3. 回答要简洁、友好、有条理
4. 适当使用emoji让回答更生动"""

# 4. 创建Agent
agent = create_react_agent(
    model=llm,
    tools=tools,
    prompt=system_prompt,
)

Agent创建流程图

---

五、第三步：运行Agent 🚀

5.1 基础对话测试

# 测试1：普通对话
result = agent.invoke({
    "messages": [("user", "你好，请介绍一下你自己")]
})
print(result["messages"][-1].content)

# 输出：
# 你好！我是小智 🤖，一个AI助手！
# 我可以帮你：
# 🔍 搜索最新信息
# 🧮 做数学计算
# 📅 查询日期和节假日
# 有什么需要帮忙的吗？😊

5.2 工具调用测试

# 测试2：联网搜索
result = agent.invoke({
    "messages": [("user", "今天有什么科技新闻？")]
})
print(result["messages"][-1].content)

# 测试3：数学计算
result = agent.invoke({
    "messages": [("user", "如果每月存5000元，年化收益率5%，定投10年后总共有多少钱？")]
})
print(result["messages"][-1].content)

# 测试4：日期查询
result = agent.invoke({
    "messages": [("user", "今天星期几？下个节假日是什么时候？")]
})
print(result["messages"][-1].content)

5.3 多轮对话测试

from langgraph.checkpoint.memory import MemorySaver

# 创建带记忆的Agent
memory = MemorySaver()

agent_with_memory = create_react_agent(
    model=llm,
    tools=tools,
    prompt=system_prompt,
    checkpointer=memory,
)

# 多轮对话
config = {"configurable": {"thread_id": "user-001"}}

# 第一轮
agent_with_memory.invoke(
    {"messages": [("user", "我叫小明，我是一名程序员")]},
    config=config
)

# 第二轮（Agent会记住你叫小明）
result = agent_with_memory.invoke(
    {"messages": [("user", "你还记得我叫什么吗？")]},
    config=config
)
# 输出：当然记得！你叫小明，是一名程序员 😊

---

六、Agent的执行过程可视化 🔍

让我们看看Agent在内部是怎么"思考"的：

6.1 一次完整的执行流程

6.2 查看中间过程

# 使用streaming查看Agent的每一步
for step in agent.stream(
    {"messages": [("user", "搜索一下今天的科技新闻")]},
    stream_mode="updates"
):
    # 打印每一步的输出
    for node, output in step.items():
        print(f"\n{'='*50}")
        print(f"📍 节点: {node}")
        print(f"{'='*50}")
        if "messages" in output:
            for msg in output["messages"]:
                print(f"  {msg.type}: {msg.content[:200]}...")

输出示例：

==================================================
📍 节点: agent
==================================================
  ai: 用户想了解今天的科技新闻，我来调用搜索工具...
  Tool Call: web_search("今日科技新闻 2025")

==================================================
📍 节点: tools  
==================================================
  tool: • OpenAI发布GPT-5...
        • 苹果推出新VR设备...

==================================================
📍 节点: agent
==================================================
  ai: 今天的科技新闻主要有：1. OpenAI发布GPT-5...

---

七、进阶：给Agent添加错误处理 🛡️

真实的Agent需要处理各种异常情况：

from langchain.agents.middleware import wrap_tool_call
from langchain.messages import ToolMessage

# 自定义错误处理中间件
@wrap_tool_call
def safe_tool_call(request, handler):
    """安全地调用工具，捕获异常"""
    try:
        return handler(request)
    except Exception as e:
        return ToolMessage(
            content=f"⚠️ 工具调用出错：{str(e)}，请尝试其他方式完成任务。",
            tool_call_id=request.tool_call["id"]
        )

# 创建带错误处理的Agent
robust_agent = create_react_agent(
    model=llm,
    tools=tools,
    prompt=system_prompt,
    middleware=[safe_tool_call],  # 添加错误处理
)

常见错误及处理策略

错误类型	原因	处理策略
🔴 API超时	网络不稳定	设置timeout + 重试
🔴 工具不存在	工具名拼写错误	错误提示 + 工具名校验
🔴 参数错误	参数格式不对	在docstring中明确格式
🔴 死循环	Agent反复调用同一工具	设置max_iterations限制

---

八、完整代码汇总 📦

把上面的代码整合在一起，就是一个完整的Agent：

"""
🤖 我的第一个AI Agent - 完整代码
功能：对话 + 搜索 + 计算 + 日期查询
"""
import os
from langchain.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver
from datetime import datetime

# ===== 1. 定义工具 =====
@tool
def web_search(query: str) -> str:
    """搜索互联网获取最新信息。当用户询问最新新闻、实时数据时使用。
    Args:
        query: 搜索关键词
    """
    # 简化版：实际项目中接入真实搜索API
    return f"搜索结果：关于'{query}'的最新信息..."

@tool
def calculator(expression: str) -> str:
    """执行数学计算。当需要精确计算时使用。
    Args:
        expression: 数学表达式
    """
    try:
        result = eval(expression, {"__builtins__": {}}, {})
        return f"计算结果：{expression} = {result}"
    except Exception as e:
        return f"计算错误：{e}"

@tool
def date_query(action: str) -> str:
    """查询日期信息。支持 today/weekday/next_holiday。
    Args:
        action: 查询类型
    """
    today = datetime.now()
    if action == "today":
        return f"今天是 {today.strftime('%Y年%m月%d日')}"
    return f"查询结果：{action}"

# ===== 2. 创建Agent =====
tools = [web_search, calculator, date_query]
llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

agent = create_react_agent(
    model=llm,
    tools=tools,
    prompt="你是一个全能AI助手，能搜索、能计算、能查日期。回答要简洁友好！",
    checkpointer=MemorySaver(),
)

# ===== 3. 运行 =====
if __name__ == "__main__":
    config = {"configurable": {"thread_id": "demo"}}
    
    while True:
        user_input = input("\n你：")
        if user_input.lower() in ["exit", "quit", "退出"]:
            print("再见！ 👋")
            break
            
        result = agent.invoke(
            {"messages": [("user", user_input)]},
            config=config
        )
        print(f"\n助手：{result['messages'][-1].content}")

---

九、运行效果展示 🎬

你：你好！
助手：你好！我是小智 🤖，很高兴见到你！
      我可以帮你搜索信息、做计算、查日期，有什么需要帮忙的吗？😊

你：帮我算一下，如果每月定投3000元，年化8%，20年后有多少钱？
助手：让我来精确计算一下 🧮
      [调用计算器工具]
      按照每月定投3000元，年化收益率8%，复利计算20年：
      💰 最终金额约为：177,171,281 元（约1.77亿元）
      其中本金投入：72万元，收益约1.76亿元！
      复利的力量真的很惊人呢 📈

你：今天星期几？
助手：今天是2025年6月15日，星期日 😊
      周末愉快！有什么想做的吗？

---

十、本期小结 📝

步骤	内容	关键点
1️⃣	定义工具	docstring要写清楚，Agent靠它选工具
2️⃣	创建Agent	用create_react_agent一行搞定
3️⃣	运行测试	对话、搜索、计算、日期全覆盖
4️⃣	添加记忆	用MemorySaver实现多轮对话
5️⃣	错误处理	用中间件捕获工具异常

🔥 恭喜！ 你已经成功搭建了第一个AI Agent！虽然它还比较简单，但核心架构已经完整——感知、思考、行动、记忆四大模块一个不少。

下一步学习路线

本期（入门） → 第5期（选模型） → 第6期（Prompt进阶） → 第7期（Function Calling）

---

📢 下期预告：《Agent的"大脑"怎么选？GPT-4o/Claude/DeepSeek/Qwen全面横评》—— 模型选错了，Agent再好的架构也白搭！下期帮你选对"大脑"！🧠

---

📌 三连走起！代码已经跑通了，赶紧动手试试吧！ 💪

📚 专栏第4/24期，认知觉醒篇完结！下一篇进入大模型基座篇！

作者：高炉炼铁智能化技术研究者，专注钢铁冶金与人工智能 交叉领域。

👍 如果觉得有帮助，请点赞、收藏、转发！
版权归作者所有，未经许可请勿抄袭，套用，商用(或其它具有利益性行为)。
🔔 关注专栏，不错过后续精彩内容