LangChain Agent 工具集成系统开发流程

1. 项目概述

1.1 项目简介

本项目是一个基于 LangChain 框架构建的智能 Agent 系统，集成了多种工具（百科检索、实时搜索），能够根据用户查询自动选择合适的工具进行回答。系统具备完整的降级机制，在网络受限环境下也能正常运行。

本次通过Open AI的大模型进行演示

1.2 核心功能

功能模块	描述	状态
百科检索工具	基于向量数据库的文档检索，支持本地知识库查询	✅ 已实现
实时搜索工具	集成 Tavily 搜索引擎，支持实时信息获取	✅ 已实现
智能 Agent	基于 GPT-3.5-turbo 的工具调用决策引擎	✅ 已实现
降级机制	网络异常时自动切换到模拟数据模式	✅ 已实现

---

2. 技术架构

2.1 系统架构图

┌─────────────────────────────────────────────────────────────────┐
│                        用户查询入口                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Agent Executor                             │
│              (create_tool_calling_agent + AgentExecutor)        │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
    ┌───────────────┐ ┌───────────────┐ ┌───────────────┐
    │   百科检索工具  │ │  实时搜索工具  │ │    LLM        │
    │  search_baike │ │   Tavily      │ │   GPT-3.5-turbo     │
    └───────────────┘ └───────────────┘ └───────────────┘
              │               │
              ▼               ▼
    ┌───────────────┐ ┌───────────────┐
    │   FAISS       │ │   Tavily API  │
    │  向量数据库   │ │   搜索引擎    │
    └───────────────┘ └───────────────┘

2.2 技术栈

类别	技术	版本要求	用途
核心框架	LangChain	1.0+	构建 Agent 和工具链
LLM	OpenAI ChatGPT	gpt-3.5-turbo	智能决策和回答生成
向量数据库	FAISS	最新	文档向量存储和检索
搜索引擎	Tavily	最新	实时信息搜索
文档加载	WebBaseLoader	最新	网页内容抓取
文本分块	RecursiveCharacterTextSplitter	最新	长文本分块处理

---

3. 核心模块详解

class Color:
    RED = '\033[31m'
    GREEN = '\033[32m'
    YELLOW = '\033[33m'
    BLUE = '\033[34m'
    PURPLE = '\033[35m'
    CYAN = '\033[36m'
    WHITE = '\033[37m'
    RESET = '\033[0m'

3.1 颜色输出模块

设计目的: 提供终端彩色输出，便于调试和日志分级显示。

颜色常量	终端代码	用途
RED	\033[31m	错误信息
GREEN	\033[32m	成功信息
YELLOW	\033[33m	警告/降级信息
BLUE	\033[34m	标题/标签
PURPLE	\033[35m	属性名称
CYAN	\033[36m	链接/URL
WHITE	\033[37m	普通文本
RESET	\033[0m	重置颜色

使用示例:

print(f"{Color.RED}错误信息{Color.RESET}")
print(f"{Color.GREEN}成功信息{Color.RESET}")

---

3.2 百科检索工具

核心流程:

步骤	组件	作用
1	WebBaseLoader	加载网页内容
2	RecursiveCharacterTextSplitter	文本分块
3	OpenAIEmbeddings / FakeEmbeddings	生成向量
4	FAISS	向量存储
5	create_retriever_tool	创建检索工具

分块参数配置:

参数	值	说明
chunk_size	1000	每个文本块的最大字符数
chunk_overlap	200	相邻文本块的重叠字符数

降级机制:

异常场景	处理方式	代码行
网页加载失败	使用预定义的模拟文档	L29-L33
向量化失败（网络超时）	使用 FakeEmbeddings	L38-L43

---

3.3 实时搜索工具

核心流程:

步骤	组件	作用
1	langchain_tavily.TavilySearch	初始化搜索工具
2	max_results=1	配置返回结果数量

降级机制:

异常场景	处理方式
API Key 缺失/无效	创建模拟工具函数

模拟工具定义:

@tool
def tavily_search_tool(query: str) -> str:
    return f"搜索结果: {query} - 模拟数据"

---

3.4 智能 Agent

核心组件:

组件	类名	作用
LLM	ChatOpenAI	大语言模型
Prompt	ChatPromptTemplate	对话模板
Agent	create_tool_calling_agent	创建工具调用 Agent
Executor	AgentExecutor	Agent 执行器

Prompt 结构:

消息类型	内容	说明
system	“你是一个专业的助手，使用提供的工具回答用户问题。”	系统角色定义
human	“{input}”	用户输入
agent_scratchpad	MessagesPlaceholder	Agent 思考过程占位符

降级机制:

异常场景	处理方式
LLM 调用失败（网络超时）	返回模拟结果

---

4. 工具注册与调用

4.1 工具列表

工具名称	变量名	类型	描述
search_baike	retriever_tool	RetrieverTool	百科检索，基于向量数据库
tavily_search	tavily_search_tool	TavilySearch/Tool	实时搜索，基于 Tavily API

4.2 工具调用流程

用户输入 → Agent分析 → 选择工具 → 执行工具 → 返回结果 → 生成回答

---

5. 环境变量配置

5.1 必需环境变量

环境变量	说明	获取方式
OPENAI_API_KEY	OpenAI API Key	https://platform.openai.com/
TAVILY_API_KEY	Tavily 搜索 API Key	https://tavily.com/

5.2 设置方法

Windows PowerShell:

# 临时设置（当前终端有效）
$env:OPENAI_API_KEY="your-key"
$env:TAVILY_API_KEY="your-key"

# 永久设置（用户级别）
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-key", "User")
[Environment]::SetEnvironmentVariable("TAVILY_API_KEY", "your-key", "User")

---

6. 依赖安装

6.1 核心依赖

依赖包	安装命令	用途
langchain	pip install langchain	核心框架
langchain-openai	pip install langchain-openai	OpenAI 集成
langchain-community	pip install langchain-community	社区工具集
langchain-tavily	pip install langchain-tavily	Tavily 搜索
faiss-cpu	pip install faiss-cpu	向量数据库
python-dotenv	pip install python-dotenv	环境变量加载

6.2 一键安装

pip install langchain langchain-openai langchain-community langchain-tavily faiss-cpu python-dotenv

---

代码实现

from langchain_community.document_loaders import WebBaseLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import FAISS
from langchain_openai import OpenAIEmbeddings
from langchain_core.tools.retriever import create_retriever_tool
from langchain_core.documents import Document
import io
import sys

sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')


class Color:
    RED = '\033[31m'
    GREEN = '\033[32m'
    YELLOW = '\033[33m'
    BLUE = '\033[34m'
    PURPLE = '\033[35m'
    CYAN = '\033[36m'
    WHITE = '\033[37m'
    RESET = '\033[0m'


###############################################################################
"""
    百科搜索工具
"""
try:
    loader = WebBaseLoader("https://upimg.baike.so.com/doc/1975803-32301482.html")
    data = loader.load()
except Exception as e:
    print(f"{Color.RED}网页加载失败: {e}{Color.RESET}")
    data = [Document(page_content="猫是一种小型哺乳动物，属于猫科。猫通常有柔软的毛发、锐利的爪子和敏锐的听觉。它们是优秀的猎手，喜欢抓老鼠等小动物。猫的眼睛在黑暗中可以发光，尾巴可以帮助它们保持平衡。")]

text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
documents = text_splitter.split_documents(data)

try:
    vector = FAISS.from_documents(documents, OpenAIEmbeddings())
except Exception as e:
    print(f"{Color.RED}向量化失败: {e}{Color.RESET}")
    from langchain_core.embeddings import FakeEmbeddings
    vector = FAISS.from_documents(documents, FakeEmbeddings(size=1536))

retriever = vector.as_retriever()
retriever_tool = create_retriever_tool(retriever, "search_baike", "百科搜索")


###############################################################################
"""
Tavily是一款专为大型语言模型（LLMs）和检索增强生成（RAG）优化的搜索引擎API
"""

# from langchain_community.tools.tavily_search import TavilySearchResults
# tavily_search_tool = TavilySearchResults(max_results=1)

from langchain_tavily import TavilySearch

try:
    tavily_search_tool = TavilySearch(max_results=1)
except Exception as e:
    print(f"{Color.RED}Tavily初始化失败: {e}{Color.RESET}")
    from langchain_core.tools import tool
    @tool
    def tavily_search_tool(query: str) -> str:
        return f"搜索结果: {query} - 模拟数据"


###############################################################################


# 创建工具包
tools = [retriever_tool, tavily_search_tool]


"""
    工具包、大模型llm与标准 Agent 结合使用
"""
from langchain_openai import ChatOpenAI
from langchain_classic.agents import AgentExecutor
from langchain_classic.agents import create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

llm = ChatOpenAI(model="gpt-3.5-turbo")


prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个专业的助手，使用提供的工具回答用户问题。"),
    ("human", "{input}"),
    MessagesPlaceholder("agent_scratchpad"),
])


agent = create_tool_calling_agent(llm=llm, tools=tools, prompt=prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
#result = agent_executor.invoke({"input": "猫有哪些种类?"})
#print(f"\n{Color.BLUE}结果：{Color.RESET}")
#print(f"{Color.GREEN}{result}{Color.RESET}")
try:
    result = agent_executor.invoke({"input": "今天深圳的天气怎么样?"})
    print(f"\n{Color.BLUE}结果：{Color.RESET}")
    print(f"{Color.GREEN}{result}{Color.RESET}")
except Exception as e:
    print(f"\n{Color.RED}Agent 执行失败: {e}{Color.RESET}")
    print(f"{Color.YELLOW}使用模拟数据：{Color.RESET}")
    print(f"{Color.GREEN}{{'input': '今天深圳的天气怎么样?', 'output': '深圳今日天气晴朗，气温 28°C，湿度 65%，适合出行。'}}{Color.RESET}")

7. 运行说明

7.1 直接运行

cd e:\AI-Study\AI-demo\day-07\agent
python agent_tools_llm.py

7.2 预期输出

正常模式:

搜索结果：
[{'url': '...', 'content': '...'}]

结果：
{'input': '今天深圳的天气怎么样?', 'output': '深圳今日天气晴朗...'}

降级模式:

网页加载失败: [WinError 10060] ...
向量化失败: Request timed out.
Tavily初始化失败: ...
Agent 执行失败: ...
使用模拟数据：
{'input': '今天深圳的天气怎么样?', 'output': '深圳今日天气晴朗，气温 28°C...'}

---

实际效果：

token消耗：

8. 代码优化建议

8.1 改进方向

建议	当前状态	优先级
添加 .env 文件支持	未实现	高
增加日志系统	使用 print	中
添加工具健康检查	未实现	中
支持多轮对话	未实现	低
添加配置文件	硬编码	中

8.2 待修复的废弃警告

警告来源	当前使用	建议替换
langchain-community	WebBaseLoader, FAISS	使用独立包

---

9. 故障排除

9.1 常见问题

错误信息	原因	解决方案
Request timed out	网络无法访问外网	检查网络连接或使用降级模式
Invalid API key	API Key 无效	确认 API Key 正确性
TAVILY_API_KEY not found	未设置环境变量	设置 TAVILY_API_KEY
OPENAI_API_KEY not found	未设置环境变量	设置 OPENAI_API_KEY
ModuleNotFoundError: langchain_tavily	未安装依赖	pip install langchain-tavily

---