纲要
- 工具封装总览
- 钉钉待办:创建任务,支持优先级与截止时间
- 钉钉日历:忙闲查询、创建、查询、修改、删除
- 核心设计模式
Pydantic模型绑定:确保参数结构稳定,减少大模型传参错误- 工具颗粒度拆分:每个工具执行原子操作,由智能体自主组合
- 人工确认机制:删除等高风险操作前引入用户二次确认
- 钉钉 API 交互基础
access_token获取与缓存策略union_id作为用户身份标识
- 各工具详细实现
create_todo:待办创建check_busy_status:忙闲状态查询create_calendar_event:日程创建(内置冲突检测)query_calendar_events:日程检索modify_calendar_event:日程修改(先查后改)request_delete_event+confirm_delete_event:确认式删除
- 完整可运行示例
- 总结与相关度说明
工具封装的整体思路
智能体的能力边界完全由所挂载的工具集决定。在与外部系统(如钉钉)交互时,每个工具的设计应遵循三项基本原则:
- 原子化:每个工具只承担单一职责,例如日程的增加、删除、修改、查询分别独立实现,便于智能体按需组合。
- 结构化入参:所有工具均通过
Pydantic声明参数模型,强制类型与字段约束,有效降低大模型生成参数时的随机错误。 - 容错与确认:对于删除等不可逆操作,采用两阶段流程,先检索并请求用户确认,确认后方可执行,避免误操作。
基于上述原则,小浪助手深度集成了钉钉的待办与日历能力,使用户能够以自然语言直接管理工作安排。
钉钉 API 客户端封装
所有钉钉 OpenAPI 调用均需携带 access_token,因此首先封装一个独立的客户端,统一管理 Token 的获取与缓存。
# dingtalk_client.py
import time
import requests
from config import Config
class DingTalkClient:
"""钉钉API客户端,自动管理access_token的获取与刷新"""
def __init__(self):
self.app_key = Config.DINGTALK_APP_KEY
self.app_secret = Config.DINGTALK_APP_SECRET
self.union_id = Config.DINGTALK_UNION_ID
self._token = None
self._expire_at = 0
def get_token(self) -> str:
"""获取有效access_token,若缓存未过期则直接返回,否则重新获取"""
if self._token and time.time() < self._expire_at:
return self._token
resp = requests.get(
"https://oapi.dingtalk.com/gettoken",
params={"appkey": self.app_key, "appsecret": self.app_secret}
)
data = resp.json()
if data.get("errcode") == 0:
self._token = data["access_token"]
self._expire_at = time.time() + 7000 # 提前100秒刷新
return self._token
raise RuntimeError(f"获取access_token失败: {data}")
# 全局客户端实例
client = DingTalkClient()
工具一:钉钉待办创建
该工具允许智能体根据对话内容自动创建待办任务,支持设置优先级和截止时间。
# tools/todo.py
import requests
from datetime import datetime
from langchain.tools import tool
from pydantic import BaseModel, Field
from dingtalk_client import client
class TodoInput(BaseModel):
subject: str = Field(description="待办标题,必填")
description: str = Field(default="", description="详细描述")
due_time: int = Field(default=0, description="截止时间的毫秒时间戳,例如1735689600000")
priority: int = Field(default=20, description="优先级:10较低,20普通,30紧急,40非常紧急")
@tool(args_schema=TodoInput)
def create_todo(subject: str, description: str = "",
due_time: int = 0, priority: int = 20) -> str:
"""
创建钉钉待办事项。适用于用户要求记录待办、跟进任务或需人工介入的场景。
"""
token = client.get_token()
url = f"https://api.dingtalk.com/v1.0/todo/users/{client.union_id}/tasks"
headers = {
"x-acs-dingtalk-access-token": token,
"Content-Type": "application/json"
}
body = {
"subject": subject,
"description": description,
"priority": priority,
"createdTime": int(datetime.now().timestamp() * 1000)
}
if due_time:
body["dueTime"] = due_time
resp = requests.post(url, headers=headers, json=body)
data = resp.json()
if resp.status_code == 200 and "id" in data:
return f"已创建待办「{subject}」,优先级 {priority}"
return f"创建失败: {data}"
工具二:日程忙闲查询
在创建新日程前,首先查询目标时间段是否已被占用,避免时间冲突。
# tools/calendar_busy.py
import requests
from langchain.tools import tool
from pydantic import BaseModel, Field
from dingtalk_client import client
class BusyCheckInput(BaseModel):
start_time: str = Field(description="查询开始时间,ISO8601格式,如2025-01-15T09:00:00+08:00")
end_time: str = Field(description="查询结束时间,ISO8601格式")
@tool(args_schema=BusyCheckInput)
def check_busy_status(start_time: str, end_time: str) -> str:
"""查询指定时间段内的忙闲状态,用于判断新日程是否与已有安排冲突。"""
token = client.get_token()
url = f"https://api.dingtalk.com/v1.0/calendar/users/{client.union_id}/busy"
headers = {
"x-acs-dingtalk-access-token": token,
"Content-Type": "application/json"
}
body = {
"userIds": [client.union_id],
"startTime": start_time,
"endTime": end_time
}
resp = requests.post(url, headers=headers, json=body)
data = resp.json()
busy_list = data.get("result", [])
if not busy_list:
return "该时段空闲,可以安排日程。"
return "该时段已有以下安排:" + str(busy_list)
工具三:日程创建(内置冲突检测)
创建日程时,自动调用忙闲查询进行冲突检测,若存在冲突则提示用户更换时间。
# tools/calendar_create.py
import requests
from langchain.tools import tool
from pydantic import BaseModel, Field
from dingtalk_client import client
class CreateEventInput(BaseModel):
summary: str = Field(description="日程标题")
start_time: str = Field(description="开始时间,ISO8601格式")
end_time: str = Field(description="结束时间,ISO8601格式")
description: str = Field(default="", description="日程详情")
is_all_day: bool = Field(default=False, description="是否为全天事件")
@tool(args_schema=CreateEventInput)
def create_calendar_event(summary: str, start_time: str, end_time: str,
description: str = "", is_all_day: bool = False) -> str:
"""在钉钉日历中创建新日程,创建前自动检测时间冲突。"""
token = client.get_token()
# 先调用忙闲查询
busy_check = check_busy_status.invoke({
"start_time": start_time,
"end_time": end_time
})
if "该时段空闲" not in busy_check:
return f"时间冲突:{busy_check},请更换时段。"
url = f"https://api.dingtalk.com/v1.0/calendar/users/{client.union_id}/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,
"isAllDay": is_all_day
}
resp = requests.post(url, headers=headers, json=body)
data = resp.json()
if resp.status_code == 200 and "id" in data:
return f"已创建日程「{summary}」,{start_time} ~ {end_time}"
return f"创建失败: {data}"
工具四:日程查询
按指定时间段检索已有的日程安排,返回日程列表及基本信息。
# tools/calendar_query.py
import requests
from langchain.tools import tool
from pydantic import BaseModel, Field
from dingtalk_client import client
class QueryInput(BaseModel):
start_time: str = Field(description="查询开始时间,ISO8601格式")
end_time: str = Field(description="查询结束时间,ISO8601格式")
@tool(args_schema=QueryInput)
def query_calendar_events(start_time: str, end_time: str) -> str:
"""查询指定时间段内的钉钉日程列表。"""
token = client.get_token()
url = f"https://api.dingtalk.com/v1.0/calendar/users/{client.union_id}/events"
headers = {"x-acs-dingtalk-access-token": token}
params = {"startTime": start_time, "endTime": end_time}
resp = requests.get(url, headers=headers, params=params)
data = resp.json()
events = data.get("events", [])
if not events:
return "该时段暂无日程。"
lines = []
for e in events:
lines.append(f"- {e['summary']} ({e['start']['dateTime']} ~ {e['end']['dateTime']}) [ID:{e['id']}]")
return "\n".join(lines)
工具五:日程修改(先查后改)
修改日程采用两步策略:先查询获得目标日程 ID,再根据用户意图更新指定字段。
# tools/calendar_modify.py
import requests
from typing import Optional
from langchain.tools import tool
from pydantic import BaseModel, Field
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from dingtalk_client import client
from config import Config
class ModifyInput(BaseModel):
query_start: str = Field(description="查询日程的开始时间,ISO8601格式")
query_end: str = Field(description="查询日程的结束时间,ISO8601格式")
user_intent: str = Field(description="用户的修改意图描述,例如「把会议改到下午三点」")
new_summary: Optional[str] = Field(default=None, description="新的日程标题")
new_start: Optional[str] = Field(default=None, description="新的开始时间")
new_end: Optional[str] = Field(default=None, description="新的结束时间")
def extract_target_event(query_result: str, user_intent: str) -> dict:
"""使用LLM从查询结果中提取与用户意图最匹配的日程ID"""
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
prompt = ChatPromptTemplate.from_template(
"根据用户意图和以下日程列表,找出最匹配的日程,返回其ID。"
"只返回ID字符串,不要其他内容。\n"
"用户意图: {intent}\n日程列表: {events}\nID:"
)
chain = prompt | llm | StrOutputParser()
event_id = chain.invoke({"intent": user_intent, "events": query_result})
return {"event_id": event_id.strip()}
@tool(args_schema=ModifyInput)
def modify_calendar_event(query_start: str, query_end: str, user_intent: str,
new_summary: str = None, new_start: str = None,
new_end: str = None) -> str:
"""修改已有日程。需先查询得到目标日程,再执行更新。"""
token = client.get_token()
# 1. 查询现有日程
events_info = query_calendar_events.invoke({
"start_time": query_start,
"end_time": query_end
})
if "暂无日程" in events_info:
return f"未找到匹配的日程。查询结果: {events_info}"
# 2. 提取目标日程ID
target = extract_target_event(events_info, user_intent)
event_id = target.get("event_id", "")
if not event_id:
return f"无法匹配用户意图对应的日程。查询结果: {events_info}"
# 3. 构造更新请求
url = f"https://api.dingtalk.com/v1.0/calendar/users/{client.union_id}/events/{event_id}"
headers = {
"x-acs-dingtalk-access-token": token,
"Content-Type": "application/json"
}
body = {}
if new_summary:
body["summary"] = new_summary
if new_start:
body["start"] = {"dateTime": new_start, "timeZone": "Asia/Shanghai"}
if new_end:
body["end"] = {"dateTime": new_end, "timeZone": "Asia/Shanghai"}
resp = requests.put(url, headers=headers, json=body)
if resp.status_code == 200:
return f"日程 {event_id} 已更新。"
return f"更新失败: {resp.json()}"
工具六:删除日程(带人工确认)
删除属于高危操作,因此拆分为两个独立工具:先检索目标并请求确认,用户明确同意后再执行删除。
# tools/calendar_delete.py
import requests
from langchain.tools import tool
from pydantic import BaseModel, Field
from langchain_openai import ChatOpenAI
from langchain.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from dingtalk_client import client
from config import Config
class DeleteRequestInput(BaseModel):
query_start: str = Field(description="查询开始时间,ISO8601格式")
query_end: str = Field(description="查询结束时间,ISO8601格式")
user_intent: str = Field(description="用户想要删除的日程描述")
class ConfirmDeleteInput(BaseModel):
event_id: str = Field(description="确认要删除的日程ID")
@tool(args_schema=DeleteRequestInput)
def request_delete_event(query_start: str, query_end: str,
user_intent: str) -> str:
"""请求删除某个日程。仅做查询和匹配,返回确认信息,不执行真实删除。"""
from tools.calendar_query import query_calendar_events
events_info = query_calendar_events.invoke({
"start_time": query_start,
"end_time": query_end
})
if "暂无日程" in events_info:
return f"未找到匹配的日程。查询结果: {events_info}"
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
prompt = ChatPromptTemplate.from_template(
"根据用户意图和以下日程列表,找出最匹配的日程,返回其ID。只返回ID字符串。\n"
"用户意图: {intent}\n日程列表: {events}\nID:"
)
chain = prompt | llm | StrOutputParser()
event_id = chain.invoke({"intent": user_intent, "events": events_info})
return f"找到日程 ID={event_id.strip()},是否确认删除?请用户明确回复「确认」以执行。"
@tool(args_schema=ConfirmDeleteInput)
def confirm_delete_event(event_id: str) -> str:
"""确认并执行删除指定日程的操作。仅当用户明确同意后才调用。"""
token = client.get_token()
url = f"https://api.dingtalk.com/v1.0/calendar/users/{client.union_id}/events/{event_id}"
headers = {"x-acs-dingtalk-access-token": token}
resp = requests.delete(url, headers=headers)
if resp.status_code == 200:
return f"日程 {event_id} 已成功删除。"
return f"删除失败: {resp.json()}"
完整可运行示例
将所有工具注册到 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.todo import create_todo
from tools.calendar_busy import check_busy_status
from tools.calendar_create import create_calendar_event
from tools.calendar_query import query_calendar_events
from tools.calendar_modify import modify_calendar_event
from tools.calendar_delete import request_delete_event, confirm_delete_event
tools = [
create_todo,
check_busy_status,
create_calendar_event,
query_calendar_events,
modify_calendar_event,
request_delete_event,
confirm_delete_event,
]
def main():
llm = ChatOpenAI(model="gpt-4", temperature=0)
prompt = ChatPromptTemplate.from_messages([
("system", "你是小浪助手,可使用钉钉待办和日历工具帮助用户。重要操作需用户确认。"),
MessagesPlaceholder("chat_history"),
("human", "{input}"),
MessagesPlaceholder("agent_scratchpad")
])
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True,
handle_parsing_errors=True)
# 测试:创建日程
res = executor.invoke({"input": "明天上午9点到11点帮我安排一个项目启动会"})
print("回复:", res["output"])
# 测试:修改日程
res = executor.invoke({"input": "把明天的项目启动会改到下午2点"})
print("回复:", res["output"])
# 测试:删除(会先请求确认)
res = executor.invoke({"input": "把明天的项目启动会删掉"})
print("回复:", res["output"])
if __name__ == "__main__":
main()
运行前请确保 .env 文件中已配置 DINGTALK_APP_KEY、DINGTALK_APP_SECRET、DINGTALK_UNION_ID 以及有效的大模型 API Key。
API 速览
本节汇总博客中涉及的核心钉钉 OpenAPI 端点及其调用方式。
| API 功能 | 方法 | 端点 | 关键参数 |
|---|---|---|---|
| 获取 access_token | GET | https://oapi.dingtalk.com/gettoken | appkey, appsecret |
| 创建待办 | POST | /v1.0/todo/users/{unionId}/tasks | subject, description, priority, dueTime |
| 查询忙闲 | POST | /v1.0/calendar/users/{unionId}/busy | userIds, startTime, endTime |
| 创建日程 | POST | /v1.0/calendar/users/{unionId}/events | summary, start, end, description, isAllDay |
| 查询日程 | GET | /v1.0/calendar/users/{unionId}/events | startTime, endTime |
| 修改日程 | PUT | /v1.0/calendar/users/{unionId}/events/{eventId} | summary, start, end |
| 删除日程 | DELETE | /v1.0/calendar/users/{unionId}/events/{eventId} | 无 |
Demo 示例
运行说明
- 克隆项目并安装依赖:
pip install langchain langchain-openai requests pydantic python-dotenv - 在项目根目录创建
.env文件,填入钉钉应用凭证及大模型 API Key。 - 执行
python main.py启动智能体,输入自然语言指令进行测试。
关键逻辑
- 智能体使用
create_tool_calling_agent,自动根据用户输入选择合适的工具。 - 删除操作因拆分为请求确认和确认执行两步,智能体会在请求确认后等待用户明确回复“确认”才会调用删除接口。
- 日程创建时自动内置冲突检测,有效避免重复预订。
技术点总结
- 基于 LangChain 的 Tool 装饰器与 Pydantic 参数校验。
- 钉钉 OpenAPI 的 Token 缓存与统一客户端管理。
- 原子化工具设计 + 人工确认模式,提升系统可靠性。
参考文档
官方文档
参考链接
总结
本文系统性地实现了基于钉钉 OpenAPI 的待办与日历工具集,涵盖了待办创建、忙闲查询、日程增删改查等核心功能,并在删除操作中引入了人工确认的两阶段流程,有效降低了误操作风险。所有工具均采用 Pydantic 结构化入参,配合 LangChain 的装饰器模式,确保了智能体调用的稳定性与准确性。
该工具集可直接嵌入任何 LangChain 智能体项目,使用户能够通过自然语言无缝管理钉钉日程与待办。本文完整覆盖了钉钉待办创建、日历忙闲查询、日程增删改查的实现细节,并提供了可运行的示例代码,为开发者构建企业级 AI Agent 提供了实用参考。
128



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



