纲要
- 工具在智能体架构中的核心定位
- 工具设计三原则
- 最小颗粒度与功能解耦
- 结构化参数:
Pydantic模型绑定 - 工具描述与
@tool装饰器的文档化
- 四大工具实现详解
- 在线搜索:
SerpAPI封装 - 知识库检索:
Chroma向量库 + 查询重写 - 钉钉待办:情感阈值触发创建
- 钉钉日历:增删查改四合一功能
- 在线搜索:
- 钉钉 API 客户端封装(含 Token 缓存)
- 完整可运行示例与执行流程
- 总结与相关度说明
工具:智能体的能力边界
在 LangChain 生态中,工具(Tool)是将外部能力接入大模型的关键桥梁。大模型本身不具备实时信息获取、私有数据检索或外部系统操作的能力,这些功能需通过工具暴露为模型可调用的函数接口。每个工具本质上是一个可被模型调用的函数,接收结构化输入并返回执行结果。
工具设计的优劣直接影响智能体的可用性与稳定性。以下是三个核心设计原则:
-
最小颗粒度
工具应拆分为原子操作,每个工具只完成一项明确任务。复杂流程由模型自行组合调用,而非在工具内部实现编排逻辑。 -
结构化输入
所有工具参数必须绑定Pydantic模型,明确字段类型与描述。这能显著降低大模型生成非法参数的概率,同时提升工具调用的成功率。 -
清晰的功能描述
每个工具的 docstring 会被自动注入到系统提示词中,成为模型选择工具的唯一依据。描述应精确、完整,避免歧义。
工具集概览
本方案为钉钉智能客服集成四类工具,覆盖信息获取与日程管理场景:
| 工具名称 | 功能描述 | 关键技术依赖 |
|---|---|---|
web_search | 在线搜索实时信息 | SerpAPIWrapper |
search_knowledge_base | 检索私有知识库 | Chroma + 查询重写 |
create_todo | 创建钉钉待办事项 | 钉钉 API + Pydantic |
manage_calendar | 增删查改钉钉日程 | 钉钉 API + 四子工具 |
环境准备与项目结构
依赖安装(基于 Python 3.10+,LangChain 0.3.x 系列):
pip install langchain==0.3.0 langchain-openai==0.2.0 langchain-community==0.3.0 chromadb==0.5.0 pydantic==2.5.0 python-dotenv==1.0.0 google-search-results==2.4.2 requests==2.31.0
项目目录结构:
tools_project/
├── config.py # 配置加载
├── dingtalk_client.py # 钉钉 API 封装
├── tools.py # 工具定义
├── main.py # Agent 执行入口
└── .env # 环境变量
配置管理(config.py)
配置类集中管理所有环境变量,便于维护与切换。
# config.py
import os
from dotenv import load_dotenv
load_dotenv()
class Config:
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
OPENAI_BASE_URL = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
SERPAPI_API_KEY = os.getenv("SERPAPI_API_KEY")
DINGTALK_APP_KEY = os.getenv("DINGTALK_APP_KEY")
DINGTALK_APP_SECRET = os.getenv("DINGTALK_APP_SECRET")
DINGTALK_AGENT_ID = os.getenv("DINGTALK_AGENT_ID")
CHROMA_PERSIST_DIR = os.getenv("CHROMA_PERSIST_DIR", "./chroma_db")
钉钉客户端封装(dingtalk_client.py)
钉钉开放平台 API 使用 access_token 进行鉴权,有效期 7200 秒。客户端负责获取并缓存 Token,避免重复请求。
# dingtalk_client.py
import requests
import time
from config import Config
class DingTalkClient:
def __init__(self):
self.app_key = Config.DINGTALK_APP_KEY
self.app_secret = Config.DINGTALK_APP_SECRET
self.agent_id = Config.DINGTALK_AGENT_ID
self._token = None
self._expire_time = 0
def get_access_token(self) -> str:
if self._token and time.time() < self._expire_time:
return self._token
url = "https://oapi.dingtalk.com/gettoken"
params = {"appkey": self.app_key, "appsecret": self.app_secret}
resp = requests.get(url, params=params, timeout=10)
data = resp.json()
if data.get("errcode") == 0:
self._token = data["access_token"]
self._expire_time = time.time() + 7000 # 提前 200 秒刷新
return self._token
raise Exception(f"获取钉钉 token 失败: {data}")
工具定义(tools.py)
本节实现全部工具函数,每个工具均使用 @tool 装饰器,并绑定 Pydantic 参数模型。
导入与参数模型
# tools.py
import requests
import json
from typing import List, Optional
from datetime import datetime
from langchain.tools import tool
from langchain_community.utilities import SerpAPIWrapper
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.vectorstores import Chroma
from langchain.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field
from config import Config
from dingtalk_client import DingTalkClient
# ---------- Pydantic 参数模型 ----------
class TodoInput(BaseModel):
subject: str = Field(description="待办事项标题")
description: Optional[str] = Field(None, description="详细描述")
priority: int = Field(20, description="优先级,数字越小越优先,默认 20")
class CalendarEventInput(BaseModel):
summary: str = Field(description="日程标题")
start_time: str = Field(description="开始时间,ISO 8601 格式,如 2025-01-01T10:00:00+08:00")
end_time: str = Field(description="结束时间,ISO 8601 格式")
location: Optional[str] = Field(None, description="地点")
description: Optional[str] = Field(None, description="日程描述")
class QueryCalendarInput(BaseModel):
start_time: str = Field(description="查询时间段的开始,ISO 8601 格式")
end_time: str = Field(description="查询时间段的结束,ISO 8601 格式")
class ModifyCalendarInput(BaseModel):
event_id: str = Field(description="要修改的日程 ID")
summary: Optional[str] = Field(None, description="新标题")
start_time: Optional[str] = Field(None, description="新开始时间")
end_time: Optional[str] = Field(None, description="新结束时间")
class DeleteCalendarInput(BaseModel):
event_id: str = Field(description="要删除的日程 ID")
搜索工具
# ---------- 搜索工具 ----------
@tool
def web_search(query: str) -> str:
"""在线搜索最新信息。当需要实时数据、新闻或未知事实时使用此工具。"""
search = SerpAPIWrapper(serpapi_api_key=Config.SERPAPI_API_KEY)
return search.run(query)
知识库检索工具
知识库工具包含查询重写逻辑,通过生成多个语义变体提高召回率。向量库需预先创建并填充数据。
# ---------- 知识库工具 ----------
embeddings = OpenAIEmbeddings(
openai_api_key=Config.OPENAI_API_KEY,
base_url=Config.OPENAI_BASE_URL
)
vectorstore = Chroma(
persist_directory=Config.CHROMA_PERSIST_DIR,
embedding_function=embeddings
)
def rewrite_query(original: str) -> List[str]:
"""查询重写:生成 3 个语义变体,提升召回率。"""
llm = ChatOpenAI(
model="gpt-3.5-turbo",
temperature=0.3,
openai_api_key=Config.OPENAI_API_KEY,
base_url=Config.OPENAI_BASE_URL
)
prompt = ChatPromptTemplate.from_template(
"将以下用户问题改写为 3 个不同角度但语义相同的查询,每个查询单独一行,不要编号。\n"
"问题: {query}\n改写的查询:"
)
chain = prompt | llm
result = chain.invoke({"query": original})
queries = [q.strip() for q in result.content.split("\n") if q.strip()]
return [original] + queries
@tool
def search_knowledge_base(query: str) -> str:
"""查询内部知识库,获取 LangChain、AI Agent 等专业知识。"""
queries = rewrite_query(query)
all_docs = []
for q in queries:
docs = vectorstore.similarity_search(q, k=2)
all_docs.extend(docs)
# 去重并取前 5 个最相关结果
unique_contents = []
seen = set()
for doc in all_docs:
if doc.page_content not in seen:
seen.add(doc.page_content)
unique_contents.append(doc.page_content)
return "\n\n".join(unique_contents[:5])
钉钉待办工具
# ---------- 钉钉待办工具 ----------
ding_client = DingTalkClient()
@tool(args_schema=TodoInput)
def create_todo(subject: str, description: Optional[str] = None, priority: int = 20) -> str:
"""创建钉钉待办事项。当用户要求记录事务、投诉或表达强烈负面情绪时使用。"""
token = ding_client.get_access_token()
url = "https://api.dingtalk.com/v1.0/todo/users/me/tasks"
headers = {
"x-acs-dingtalk-access-token": token,
"Content-Type": "application/json"
}
body = {
"subject": subject,
"priority": priority,
"createdTime": int(datetime.now().timestamp() * 1000)
}
if description:
body["description"] = description
resp = requests.post(url, headers=headers, json=body, timeout=10)
data = resp.json()
if resp.status_code == 200 and "id" in data:
return f"已创建待办「{subject}」,优先级 {priority}"
return f"创建待办失败: {data}"
钉钉日历工具(增删查改)
# ---------- 钉钉日历工具 ----------
@tool(args_schema=CalendarEventInput)
def create_calendar_event(summary: str, start_time: str, end_time: str,
location: Optional[str] = None, description: Optional[str] = None) -> str:
"""在钉钉日历中创建新日程。所有时间参数均为 ISO 8601 格式字符串。"""
token = ding_client.get_access_token()
url = "https://api.dingtalk.com/v1.0/calendar/users/me/events"
headers = {
"x-acs-dingtalk-access-token": token,
"Content-Type": "application/json"
}
body = {
"summary": summary,
"start": {"dateTime": start_time, "timeZone": "Asia/Shanghai"},
"end": {"dateTime": end_time, "timeZone": "Asia/Shanghai"},
"description": description or ""
}
if location:
body["location"] = {"displayName": location}
resp = requests.post(url, headers=headers, json=body, timeout=10)
data = resp.json()
if resp.status_code == 200 and "id" in data:
return f"已创建日程「{summary}」,时间 {start_time} ~ {end_time}"
return f"创建日程失败: {data}"
@tool(args_schema=QueryCalendarInput)
def query_calendar(start_time: str, end_time: str) -> str:
"""查询指定时间段内的钉钉日程。"""
token = ding_client.get_access_token()
url = "https://api.dingtalk.com/v1.0/calendar/users/me/events"
params = {"startTime": start_time, "endTime": end_time}
headers = {"x-acs-dingtalk-access-token": token}
resp = requests.get(url, headers=headers, params=params, timeout=10)
data = resp.json()
events = data.get("events", [])
if not events:
return "该时段暂无日程。"
result = []
for e in events:
result.append(f"- {e['summary']} ({e['start']['dateTime']} ~ {e['end']['dateTime']})")
return "\n".join(result)
@tool(args_schema=ModifyCalendarInput)
def modify_calendar_event(event_id: str, summary: Optional[str] = None,
start_time: Optional[str] = None, end_time: Optional[str] = None) -> str:
"""修改指定日程的标题或时间。"""
token = ding_client.get_access_token()
url = f"https://api.dingtalk.com/v1.0/calendar/users/me/events/{event_id}"
headers = {
"x-acs-dingtalk-access-token": token,
"Content-Type": "application/json"
}
body = {}
if summary:
body["summary"] = summary
if start_time:
body["start"] = {"dateTime": start_time, "timeZone": "Asia/Shanghai"}
if end_time:
body["end"] = {"dateTime": end_time, "timeZone": "Asia/Shanghai"}
resp = requests.put(url, headers=headers, json=body, timeout=10)
if resp.status_code == 200:
return f"日程 {event_id} 已更新。"
return f"更新失败: {resp.json()}"
@tool(args_schema=DeleteCalendarInput)
def delete_calendar_event(event_id: str) -> str:
"""删除指定的钉钉日程。"""
token = ding_client.get_access_token()
url = f"https://api.dingtalk.com/v1.0/calendar/users/me/events/{event_id}"
headers = {"x-acs-dingtalk-access-token": token}
resp = requests.delete(url, headers=headers, timeout=10)
if resp.status_code == 200:
return f"日程 {event_id} 已删除。"
return f"删除失败: {resp.json()}"
# 汇总工具列表
ALL_TOOLS = [
web_search,
search_knowledge_base,
create_todo,
create_calendar_event,
query_calendar,
modify_calendar_event,
delete_calendar_event,
]
完整运行示例(main.py)
以下代码将工具集成至 LangChain Agent,实现自动工具调用。
# main.py
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
from config import Config
from tools import ALL_TOOLS
def main():
llm = ChatOpenAI(
model="gpt-3.5-turbo",
temperature=0,
openai_api_key=Config.OPENAI_API_KEY,
base_url=Config.OPENAI_BASE_URL,
)
prompt = ChatPromptTemplate.from_messages([
("system", "你是一个智能助手,可以使用工具帮助用户。"),
MessagesPlaceholder("chat_history"),
("human", "{input}"),
MessagesPlaceholder("agent_scratchpad")
])
agent = create_tool_calling_agent(llm, ALL_TOOLS, prompt)
agent_executor = AgentExecutor(
agent=agent,
tools=ALL_TOOLS,
verbose=True,
handle_parsing_errors=True,
)
# 测试搜索
print("--- 测试搜索 ---")
res = agent_executor.invoke({"input": "今天的科技头条有哪些?"})
print("回复:", res["output"][:200])
# 测试待办创建(模拟负面情绪触发)
print("\n--- 测试待办创建 ---")
res = agent_executor.invoke({"input": "我非常生气!你们的产品根本用不了,立刻给我处理!"})
print("回复:", res["output"])
if __name__ == "__main__":
main()
运行说明
-
在项目根目录创建
.env文件,填入以下环境变量:OPENAI_API_KEY:OpenAI API 密钥OPENAI_BASE_URL(可选):API 代理地址SERPAPI_API_KEY:SerpAPI 密钥DINGTALK_APP_KEY:钉钉应用 KeyDINGTALK_APP_SECRET:钉钉应用 SecretDINGTALK_AGENT_ID:钉钉应用 Agent IDCHROMA_PERSIST_DIR(可选):向量库持久化目录
-
若需启用知识库工具,需预先运行嵌入脚本将文档写入 Chroma。
-
执行
python main.py启动测试。
设计思想回顾
上述实现完整贯彻了工具设计三原则:
- 最小颗粒度:日历的增删查改拆分为四个独立工具,模型可自由组合实现复杂操作(如“将明天所有会议推迟一小时”先查询后逐一修改)。
- 结构化输入:所有工具参数通过
args_schema绑定Pydantic模型,大模型传参错误率显著降低。 - 工具描述即文档:每个
@tool函数的 docstring 自动成为工具描述,是模型选择工具的唯一依据,必须精确无歧义。
工具开发的精髓在于设计出能被智能体高效调用的接口。掌握这些模式后,可将任意外部系统(CRM、ERP、IoT)快速接入 Agent 生态。
API 速览
本方案涉及的核心 API 如下:
LangChain 工具装饰器
@tool 装饰器将普通函数转换为 LangChain 工具对象,支持绑定参数模型。
- 所属库:
langchain.tools - 方法签名:
@tool(func: Optional[Callable] = None, args_schema: Optional[Type[BaseModel]] = None) - 参数说明:
args_schema:可选,指向Pydantic模型类,用于结构化参数校验。
- 返回值:
Tool实例
SerpAPIWrapper
封装 SerpAPI 搜索接口,返回网页摘要与链接。
- 所属库:
langchain_community.utilities - 初始化:
SerpAPIWrapper(serpapi_api_key: str) - 调用:
run(query: str) -> str
Chroma 向量数据库
用于本地向量存储与相似性检索。
- 所属库:
chromadb,通过langchain_community.vectorstores集成 - 初始化:
Chroma(persist_directory: str, embedding_function: Embeddings) - 检索:
similarity_search(query: str, k: int) -> List[Document]
钉钉开放 API
| 接口功能 | 方法 | URL 模板 |
|---|---|---|
| 获取 Access Token | GET | https://oapi.dingtalk.com/gettoken |
| 创建待办 | POST | https://api.dingtalk.com/v1.0/todo/users/me/tasks |
| 创建日程 | POST | https://api.dingtalk.com/v1.0/calendar/users/me/events |
| 查询日程 | GET | https://api.dingtalk.com/v1.0/calendar/users/me/events |
| 修改日程 | PUT | https://api.dingtalk.com/v1.0/calendar/users/me/events/{event_id} |
| 删除日程 | DELETE | https://api.dingtalk.com/v1.0/calendar/users/me/events/{event_id} |
所有钉钉 API 均需在请求头中携带 x-acs-dingtalk-access-token。
Demo 示例
本仓库提供完整可运行示例,核心流程如下:
运行说明
- 环境:Python 3.10+,已安装依赖项。
- 配置:正确填写
.env文件中的所有密钥。 - 启动:在项目目录下执行
python main.py。 - 向量库:如需知识库检索,请提前运行数据导入脚本(未包含,需自行实现)。
技术点总结
- 使用
@tool装饰器将函数声明为 LangChain 工具。 - 通过
args_schema绑定Pydantic模型实现参数结构化。 - 封装钉钉 API 客户端,内置 Token 缓存与刷新机制。
- 集成 SerpAPI 实现实时搜索。
- 集成 Chroma 向量数据库实现私有知识检索,并引入查询重写提升召回率。
- 通过
create_tool_calling_agent构建支持工具调用的 Agent。
参考文档
官方文档
- LangChain Tools Documentation
- LangChain Tool Calling Agents
- SerpAPI Python Package
- ChromaDB Documentation
- 钉钉开放平台 API 文档
参考链接
总结
本文围绕 AI Agent 工具设计,系统阐述了最小颗粒度、结构化参数与清晰描述三大原则,并基于 LangChain 0.3.x 实现了一个集成搜索、知识库检索、钉钉待办与日历管理的完整工具集。
关键技术栈包括 LangChain、OpenAI GPT-3.5-Turbo、SerpAPI、Chroma 向量数据库以及钉钉开放平台 API。通过 @tool 装饰器与 Pydantic 参数模型的结合,工具具备了高可复用性与低调用错误率。
文中提供的完整代码可本地运行,帮助开发者快速上手构建企业级智能体工具链。
428



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



