纲要
- 项目概览:基于 LangChain 的单智能体“小浪助手”
- 核心能力拆解
RAG知识库问答- 钉钉日程与待办管理
- 多轮对话与上下文记忆
- 情绪检测与动态优先级调整
- 系统架构
- 前端:钉钉机器人
- 调度层:
LangChainAgent - 工具集:知识库检索、在线搜索、钉钉 API
- 记忆系统:基于
Redis的长短期记忆 - 模型:大语言模型(LLM)生成与意图识别
- 单智能体概念与 LangChain 实现要点
- 实战代码详解
- 项目结构
- 环境依赖
- 配置管理
- 记忆组件(
RedisChatMessageHistory) - 工具定义(
@tool装饰器) - 情绪检测链
- Agent 构建与执行流程
- 多轮对话实现机制
- 情绪检测与自动待办的业务融合
- 完整可运行示例
- API 速览
- 参考文档
项目概览
本文构建一个名为“小浪助手”的单智能体应用,通过钉钉机器人对外提供服务。该智能体的核心功能集包括:
- 基于
RAG(Retrieval-Augmented Generation)的专业知识库问答 - 自然语言驱动的钉钉日程安排与待办管理
- 多轮对话能力,支持上下文记忆与指代消解
- 实时情绪检测,依据负面程度自动创建高优先级待办
所有业务逻辑均使用 LangChain 进行编排,工具调用由大语言模型(LLM)自主决策,记忆系统持久化于 Redis 中。本文适用 LangChain 0.3.x 及以上版本,部分 API 在 0.2.x 中亦可兼容,具体差异将在文中标注。
核心概念与架构
单智能体
在 AI 应用语境中,智能体(Agent)是一个能够感知环境、自主决策并使用工具完成任务的程序。单智能体(Single Agent)指整个系统中仅存在一个决策中心,该中心根据用户输入和当前状态决定调用哪些工具、以何种顺序调用以及如何生成最终回应。与之相对的多智能体系统则涉及多个协作或竞争的决策单元。本文聚焦于单智能体的设计、工具集成与记忆管理。
系统架构
系统整体分为输入接入、智能体决策、工具执行和记忆存储四个层次,其数据流如下图所示:
用户消息经由钉钉机器人 Webhook 进入系统后,Agent 首先进行情绪分析和意图识别,随后根据识别结果决策工具调用序列。工具执行结果与历史记忆共同输入 LLM,最终生成自然语言回复并返回给用户。
技术选型与关键模块
| 模块 | 技术/工具 |
|---|---|
| 智能体框架 | LangChain 0.3.x |
| 大语言模型 | OpenAI GPT-4 / 兼容接口的 LLM |
| 知识库 | 文档加载 → 文本分割 → 向量嵌入 → Chroma / FAISS |
| 记忆存储 | Redis(RedisChatMessageHistory) |
| 在线搜索 | SerpAPI 封装为 Tool |
| 钉钉 API | 钉钉开放平台 HTTP API,封装日程、待办调用 |
| 情绪检测 | 基于 LLM 的 LCEL 链,输出结构化 JSON |
实战代码详解
项目结构
langchain-dingtalk-agent/
├── agent.py # 主程序,Agent 定义与执行入口
├── tools/
│ ├── __init__.py
│ ├── dingtalk.py # 钉钉日程、待办工具
│ ├── knowledge.py # RAG 知识库检索工具
│ └── search.py # 在线搜索工具
├── chains/
│ ├── __init__.py
│ └── emotion.py # 情绪检测链
├── memory/
│ ├── __init__.py
│ └── redis_memory.py # Redis 记忆工厂函数
├── config.py # 环境变量与配置加载
└── requirements.txt # 项目依赖列表
环境依赖
pip install langchain langchain-openai langchain-community redis chromadb tiktoken python-dotenv
如需使用 Chroma 作为向量数据库,建议安装 langchain-chroma 专用包以获得更好的兼容性:
pip install langchain-chroma
配置管理 config.py
import os
from dotenv import load_dotenv
load_dotenv()
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
REDIS_URL = os.getenv("REDIS_URL", "redis://localhost:6379/0")
DINGTALK_APP_KEY = os.getenv("DINGTALK_APP_KEY")
DINGTALK_APP_SECRET = os.getenv("DINGTALK_APP_SECRET")
SERPAPI_API_KEY = os.getenv("SERPAPI_API_KEY")
记忆组件 memory/redis_memory.py
from langchain_community.chat_message_histories import RedisChatMessageHistory
from langchain.memory import ConversationBufferMemory
from config import REDIS_URL
def get_memory(session_id: str) -> ConversationBufferMemory:
"""为每个会话创建独立的 Redis 持久化记忆
Args:
session_id: 会话唯一标识,用于隔离不同用户的对话历史
Returns:
ConversationBufferMemory: 配置了 Redis 存储的记忆实例
"""
history = RedisChatMessageHistory(
session_id=session_id,
url=REDIS_URL,
)
return ConversationBufferMemory(
memory_key="chat_history",
chat_memory=history,
return_messages=True,
)
工具定义
LangChain 中工具(Tool)是对外部能力(如 API 调用、数据库查询等)的标准封装。本文使用 @tool 装饰器将普通函数转换为 Tool 对象,函数名即为工具名称,函数文档字符串(docstring)作为 LLM 理解工具用途的描述。
钉钉工具 tools/dingtalk.py
from langchain.tools import tool
import requests
from config import DINGTALK_APP_KEY, DINGTALK_APP_SECRET
def get_access_token() -> str:
"""获取钉钉 API 访问令牌(示例实现)"""
resp = requests.get(
"https://oapi.dingtalk.com/gettoken",
params={"appkey": DINGTALK_APP_KEY, "appsecret": DINGTALK_APP_SECRET},
timeout=10
)
resp.raise_for_status()
return resp.json().get("access_token")
@tool
def create_calendar_event(summary: str, start_time: str, end_time: str) -> str:
"""在钉钉日历中创建事件。
参数:
summary: 事件标题
start_time: ISO 8601 格式开始时间,如 '2026-08-18T10:00:00'
end_time: ISO 8601 格式结束时间
"""
token = get_access_token()
# 实际生产环境需调用钉钉日程 API:
# POST https://oapi.dingtalk.com/topapi/calendar/v2/event/create
# 参考: https://open.dingtalk.com/document/orgapp/create-calendar-event
return f"已成功创建日程:{summary},时间 {start_time} 至 {end_time}"
@tool
def create_task(content: str, priority: str = "normal") -> str:
"""创建钉钉待办。
参数:
content: 待办内容描述
priority: 优先级,可选 low/medium/normal/high
"""
token = get_access_token()
# 实际生产环境需调用钉钉待办 API:
# POST https://oapi.dingtalk.com/topapi/dingtalk/reminder/add
return f"已创建待办:{content},优先级 {priority}"
知识库工具 tools/knowledge.py
from langchain.tools import tool
from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from config import OPENAI_API_KEY
# 向量数据库实例(需预先构建并持久化)
# 注意:langchain-chroma 包中构造函数参数为 embedding_function,与社区版一致
vectorstore = Chroma(
persist_directory="./chroma_db",
embedding_function=OpenAIEmbeddings(openai_api_key=OPENAI_API_KEY)
)
@tool
def search_knowledge_base(query: str) -> str:
"""搜索专业知识库。
参数:
query: 用户问题或搜索关键词
返回:
相关文档片段拼接的字符串,若无结果则返回提示信息
"""
docs = vectorstore.similarity_search(query, k=3)
if not docs:
return "知识库中未找到相关信息。"
return "\n\n".join([d.page_content for d in docs])
在线搜索工具 tools/search.py
from langchain.tools import tool
from langchain_community.utilities import SerpAPIWrapper
import os
@tool
def web_search(query: str) -> str:
"""在线搜索最新信息,返回搜索摘要。
参数:
query: 搜索关键词
"""
search = SerpAPIWrapper(serpapi_api_key=os.getenv("SERPAPI_API_KEY"))
return search.run(query)
情绪检测链 chains/emotion.py
情绪检测使用 LangChain 的 LCEL(LangChain Expression Language)构建,通过结构化输出解析得到情绪标签与分值。
from langchain_openai import ChatOpenAI
from langchain.prompts import PromptTemplate
import json
emotion_prompt = PromptTemplate(
input_variables=["user_input"],
template="""分析以下用户消息的情绪,返回 JSON 格式 {{"emotion": "positive/neutral/negative", "score": 0-10}}。
消息:{user_input}
JSON:"""
)
def detect_emotion(user_input: str, model: str = "gpt-3.5-turbo") -> dict:
"""检测用户消息的情绪倾向
Args:
user_input: 用户输入文本
model: 使用的 LLM 模型名称
Returns:
dict: 包含 emotion 和 score 字段,默认 neutral/5
"""
llm = ChatOpenAI(model=model, temperature=0)
chain = emotion_prompt | llm
result = chain.invoke({"user_input": user_input})
try:
return json.loads(result.content)
except json.JSONDecodeError:
return {"emotion": "neutral", "score": 5}
Agent 主程序 agent.py
import os
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
from tools.dingtalk import create_calendar_event, create_task
from tools.knowledge import search_knowledge_base
from tools.search import web_search
from chains.emotion import detect_emotion
from memory.redis_memory import get_memory
from config import OPENAI_API_KEY
# 1. 工具列表
tools = [create_calendar_event, create_task, search_knowledge_base, web_search]
# 2. LLM 实例
llm = ChatOpenAI(
model="gpt-4",
temperature=0,
openai_api_key=OPENAI_API_KEY
)
# 3. 系统提示词
system_prompt = """你是小浪助手,一个钉钉智能客服。你可以:
- 回答关于产品的专业知识(调用知识库)
- 搜索最新信息(调用在线搜索)
- 管理用户的钉钉日程和待办
请友好、专业地回应用户。如果检测到用户情绪非常负面(score >= 8),主动将用户当前诉求创建为高优先级待办。"""
prompt = ChatPromptTemplate.from_messages([
("system", system_prompt),
MessagesPlaceholder("chat_history", optional=True),
("human", "{input}"),
MessagesPlaceholder("agent_scratchpad"),
])
# 4. 构建 Agent(使用 OpenAI 工具调用格式)
agent = create_openai_tools_agent(llm, tools, prompt)
# 5. 消息处理函数(钉钉 Webhook 入口)
def process_message(user_input: str, session_id: str = "default") -> str:
"""处理用户消息,返回 Agent 响应
Args:
user_input: 用户输入的文本
session_id: 会话标识,用于记忆隔离
Returns:
str: Agent 生成的回复内容
"""
# 步骤 A: 情绪检测
emotion_result = detect_emotion(user_input)
# 步骤 B: 高负面情绪触发业务规则
if emotion_result.get("emotion") == "negative" and emotion_result.get("score", 0) >= 8:
user_input += "\n(系统检测到强烈负面情绪,请主动将相关诉求创建为高优先级待办)"
# 步骤 C: 获取会话记忆
memory = get_memory(session_id)
# 步骤 D: 创建 Agent 执行器
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
memory=memory,
verbose=True,
handle_parsing_errors=True,
)
# 步骤 E: 执行
response = agent_executor.invoke({"input": user_input})
return response["output"]
# 示例运行
if __name__ == "__main__":
session = "user_123"
print("小浪助手:", process_message("帮我预定后天上午10点的会议室,主题是智能体技术讨论", session))
print("小浪助手:", process_message("我想起来后天早上有事,相关的安排调整一下吧", session))
print("小浪助手:", process_message("算了,我特别生气,你们产品太难用了!", session))
运行说明
- 在项目根目录创建
.env文件,填写以下环境变量:OPENAI_API_KEY: OpenAI API 密钥REDIS_URL: Redis 连接地址,默认为redis://localhost:6379/0SERPAPI_API_KEY: SerpAPI 密钥(如使用在线搜索)DINGTALK_APP_KEY/DINGTALK_APP_SECRET: 钉钉应用凭证
- 启动本地 Redis 服务:
redis-server - 预先构建知识库向量数据,存入
./chroma_db目录(构建脚本未在本示例中展开) - 执行
python agent.py运行控制台测试;接入钉钉时,将process_message函数挂载至 Webhook 路由即可。
多轮对话的实现机制
LangChain 中,多轮对话的核心在于 memory 组件的注入。本示例采用 ConversationBufferMemory 配合 RedisChatMessageHistory,实现以下特性:
- 持久化:对话历史存储于 Redis,服务重启后不丢失。
- 隔离性:通过
session_id区分不同用户或会话。 - 自动注入:
AgentExecutor在执行invoke时会自动将chat_history填入 Prompt 的MessagesPlaceholder位置。
每次调用 process_message 时传入相同的 session_id,Agent 即可读取完整的历史对话,从而正确理解“相关的安排”这类指代性表达。
情绪检测与自动待办的业务融合
情绪检测链通过 LLM 生成结构化 JSON,经解析得到 emotion 标签和 score 分值(0-10)。当负面分值达到阈值(≥8)时,主流程在用户输入尾部追加显式指令,引导 Agent 调用 create_task 工具。
该设计在保持 Agent 自主决策能力的前提下,以非侵入方式植入业务规则,无需修改工具定义或 Prompt 的核心结构。这是一种轻量级的规则注入模式,适用于需要在保留 LLM 灵活性同时强制触发某些动作的场景。
完整可运行示例
完整项目代码已在上文 agent.py 及配套模块中给出。以下为快速启动步骤:
- 克隆/创建项目目录,按项目结构创建所有 Python 文件。
- 安装依赖:
pip install -r requirements.txt(需自行生成 requirements.txt)。 - 配置环境变量:创建
.env文件并填入必要密钥。 - 启动 Redis:
redis-server。 - 运行:
python agent.py。
控制台将输出三轮对话的 Agent 响应,展示日程创建、上下文理解和情绪触发的待办创建能力。
API 速览
本节汇总博客中涉及的核心 API,按所属模块分类说明。
| API / 类 | 所属库 | 方法签名 | 说明 |
|---|---|---|---|
RedisChatMessageHistory | langchain_community.chat_message_histories | __init__(session_id: str, url: str) | Redis 聊天历史存储,需传入会话 ID 和连接 URL |
ConversationBufferMemory | langchain.memory | __init__(memory_key: str, chat_memory: BaseChatMessageHistory, return_messages: bool) | 对话缓冲记忆,封装历史存取逻辑 |
@tool | langchain.tools | 装饰器,将函数转为 Tool 对象 | 函数名及文档字符串自动作为工具标识与描述 |
create_openai_tools_agent | langchain.agents | create_openai_tools_agent(llm, tools, prompt) | 构建支持 OpenAI 工具调用的 Agent,返回 Runnable |
AgentExecutor | langchain.agents | __init__(agent, tools, memory, verbose, handle_parsing_errors) | Agent 执行器,管理运行循环、记忆注入与错误处理 |
Chroma | langchain_community.vectorstores | __init__(persist_directory, embedding_function) | Chroma 向量数据库客户端,支持持久化 |
OpenAIEmbeddings | langchain_openai | __init__(openai_api_key: str) | OpenAI 向量嵌入模型封装 |
SerpAPIWrapper | langchain_community.utilities | __init__(serpapi_api_key: str) | SerpAPI 搜索工具封装,返回搜索结果摘要 |
ChatOpenAI | langchain_openai | __init__(model: str, temperature: float, openai_api_key: str) | OpenAI 聊天模型客户端 |
PromptTemplate | langchain.prompts | from_template(template: str) / __init__(input_variables, template) | 提示词模板,支持变量插值 |
ChatPromptTemplate | langchain.prompts | from_messages(messages: List) | 聊天消息模板,支持 SystemMessage、HumanMessage、MessagesPlaceholder 等 |
MessagesPlaceholder | langchain.prompts | __init__(variable_name: str, optional: bool) | 占位符,用于动态注入对话历史或 Agent 思考轨迹 |
参考文档
官方文档
- LangChain 官方文档
- LangChain OpenAI 集成
- LangChain 记忆系统
- LangChain 工具定义
- LangChain Agent 构建
- 钉钉开放平台 - 日程 API
- 钉钉开放平台 - 待办 API
- Redis 官方文档
- Chroma 向量数据库文档
- SerpAPI 文档
参考链接
总结
本文完整实现了一个基于 LangChain 的钉钉智能助手“小浪助手”,系统性地覆盖了单智能体应用开发的关键技术栈:项目架构设计、工具封装与集成、Redis 持久化记忆管理、情绪检测链构建以及业务规则的无缝植入。
代码示例完整可运行,展示了如何利用 LangChain 的 Agent 框架和 LCEL 语法高效编排 LLM 与外部工具。读者可将本项目作为模板,快速扩展至多智能体协作、更多业务工具集成或切换至其他 IM 平台。
435



被折叠的 条评论
为什么被折叠?



