下面给出一个代码示例：展示如何使用 LangChain + 通义千问（Qwen），通过 ReAct Agent 安全地调用自定义工具完成数学计算任务。

示例代码取自《 AI Agent智能体开发实践》第8章。

# -*- coding: utf-8 -*-
"""
Created on Fri Jul 25 09:55:25 2025
@author: liguo
"""
from langchain.tools import tool
from langchain.agents import AgentExecutor, create_react_agent
from langchain import hub
from langchain_community.chat_models import ChatTongyi
import os
# 👇 核心计算函数，不被 @tool 装饰，避免递归调用工具对象
def _factorial(n: int) -> int:
    """内部阶乘计算函数，使用循环避免递归栈和工具调用问题"""
    if n < 0:
        raise ValueError("阶乘不支持负数")
    result = 1
    for i in range(1, n + 1):
        result *= i
    return result
 
# 👇 工具层函数，负责接收输入、类型转换、调用核心函数
@tool
def calculate_factorial(n: int) -> int:
    """计算给定数字的阶乘"""
    # 确保输入是整数（兼容字符串输入）
    if isinstance(n, str):
        n = int(n.strip())
    return _factorial(n)
 
# 工具列表
tools = [calculate_factorial]
 
# 初始化 Qwen 模型（请替换为你自己的 DashScope API Key）
llm = ChatTongyi(
    model="qwen-max",        # 也可用 qwen-turbo, qwen-plus
    temperature=0,
    #dashscope_api_key=os.getenv("DASHSCOPE_API_KEY")
    # 推荐：在终端或系统环境变量中设置 DASHSCOPE_API_KEY
)
 
# 拉取 ReAct 提示词模板
prompt = hub.pull("hwchase17/react")
 
# 创建 Agent
agent = create_react_agent(llm, tools, prompt)
 
# 创建执行器
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
 
# 执行任务
if __name__ == "__main__":
    response = executor.invoke({"input": "计算5的阶乘"})
    print("\n" + "="*50)
    print("最终结果:", response["output"])

上面这段代码 演示的核心目的可以用一句话概括：

✅ 展示如何使用 LangChain + 通义千问（Qwen），通过 ReAct Agent 安全地调用自定义工具完成数学计算任务。

下面我从 教学目的、工程目的、技术点验证目的 三个层面详细说明。

一、教学 / 学习目的（最主要）

这段代码本质上是一个 “LangChain Tool + Agent 最小可运行示例”，用来帮助学习者理解：

✅ 1️⃣ LangChain 中「工具」的正确写法

什么是 @tool
为什么要把：
- 核心逻辑函数
- 工具接口函数
  
  分开写

👉 避免初学者写出：

@tool
def factorial(n):
    return factorial(n-1)  # ❌ 无限递归

✅ 2️⃣ Agent 是如何“思考 + 行动”的

通过 ReAct Agent，演示：

Thought → Action → Observation → Final Answer

让使用者 肉眼看到 Agent 的决策过程。

✅ 3️⃣ LLM 如何与外部函数协作

说明一个关键概念：

LLM 本身不会算数

但它 知道什么时候该调用工具

二、工程 / 实践目的

这段代码不只是“能跑”，它在示范 工程级规范：

✅ 1️⃣ 避免工具递归（最重要）

通过：

_factorial()   # 不暴露
calculate_factorial()  # 工具

✅ 解决 LangChain 中最常见、最隐蔽的 Bug

✅ 适合真实项目复制

✅ 2️⃣ 工具输入容错设计

if isinstance(n, str):
    n = int(n.strip())

说明：

实际项目中，LLM 的输出是不可信的

✅ 3️⃣ 安全使用 API Key

os.getenv("DASHSCOPE_API_KEY")

✅ 不硬编码密钥

✅ 符合生产安全要求

三、技术点验证目的（你在验证什么）

这段代码同时验证了 5 个关键技术点是否可行：

验证点	是否成立
LangChain 能否正常调用 Qwen	✅
ReAct Prompt 是否有效	✅
Tool 能否被正确识别	✅
Agent 是否会陷入工具循环	❌（不会）
中文自然语言输入是否可用	✅

四、它想传达的“核心思想”

LLM + Tools = 真正的智能体

而不是：

❌ LLM 自己算数学
❌ 写死规则
❌ 手工 if-else 判断意图

而是：

✅ LLM 负责决策

✅ 工具负责执行

✅ Agent 负责编排

五、一句话总结（考试/汇报版）

该代码演示了如何利用 LangChain 构建一个基于 ReAct 模式的智能代理，通过通义千问模型调用自定义阶乘计算工具，安全地完成数学推理任务，并展示了工具解耦、输入容错和 Agent 执行流程的工程最佳实践。

ITPub博客

LangChain Tool + Agent 最小可运行示例解析