RocketRide 中 Outlook Calendar 工具节点深度指南:把 Microsoft Graph 日历 API 封装成 Agent Tools
RocketRide 中 Outlook Calendar 工具节点深度指南:把 Microsoft Graph 日历 API 封装成 Agent Tools
RocketRide 的 tool_outlook_calendar 工具节点(源码位于 nodes/src/nodes/tool_microsoft_365/outlook_calendar)把 Microsoft Graph 日历 API 的全部常用操作封装为 11 个 Agent 可直接调用的工具函数,作用对象始终是"当前操作者"(acting user)的日历。本文以该节点的官方文档(doc.md)为主体,结合 IInstance.py、client.py、共享的 graph_client.py 与 microsoft_access.py 源码,以及 test_outlook_calendar.py 测试用例,讲清每个工具的参数、Graph 调用、权限层级(readonly/write)、接线方式与底层安全机制。读完你可以直接在 RocketRide 管道里把 Outlook 日历能力交给 Agent:让它查日程、建会议、约时间、增量同步,并在出问题时用内置诊断工具定位权限故障。
一、节点定位:Agent 工具,而非数据流节点
tool_outlook_calendar 是一个 tool 类节点:没有数据 lane,所有操作都是通过 @tool_function 装饰器注册的、由 Agent 按需调用的函数(见 IInstance.py 中 outlook_calendar_check_connection 的注册方式)。它的能力面由两层访问层级(access tier)门控:
readonly:只读 —— 列出/读取事件与日历、查询会议时间建议、忙闲日程、增量同步;write(默认):在 readonly 之上追加创建/更新/删除事件、回复会议邀请、创建日历。
日历事件删除不需要额外的"硬删除"开关(不同于 Outlook Mail 的 allowHardDelete 门控),write 层级本身就足够,这一点在 microsoft_access.py 的 OUTLOOK_CALENDAR AccessSpec 中可以看到:该规格不声明任何 gate flags。
二、完整工具面:11 个 Agent Tools 与 Graph 调用映射
下表完整继承自节点文档,Graph 调用列给出真实请求端点:
| 工具 | Graph 调用 | 用途 | 层级 |
|---|---|---|---|
outlook_calendar_list_events |
GET [/calendars/{id}]/calendarView |
在时间窗口内列出事件(周期事件展开为单个 occurrence) | readonly |
outlook_calendar_get_event |
GET /events/{id} |
按 id 获取单个事件 | readonly |
outlook_calendar_create_event |
POST [/calendars/{id}]/events |
创建事件,可选邀请与会者 | write |
outlook_calendar_update_event |
PATCH /events/{id} |
更新事件——只改传入的字段 | write |
outlook_calendar_delete_event |
DELETE /events/{id} |
删除事件 | write |
outlook_calendar_respond |
POST /events/{id}/{accept|decline|tentativelyAccept} |
回复会议邀请 | write |
outlook_calendar_find_meeting_times |
POST /findMeetingTimes |
为一组与会者推荐会议时间 | readonly |
outlook_calendar_get_schedule |
POST /calendar/getSchedule |
获取多个邮箱的忙闲日程 | readonly |
outlook_calendar_list_calendars |
GET /calendars |
列出邮箱中的日历 | readonly |
outlook_calendar_create_calendar |
POST /calendars |
新建日历 | write |
outlook_calendar_delta_sync |
GET /calendarView/delta |
通过 delta link 增量同步日历视图 | readonly |
outlook_calendar_check_connection |
GET /calendar + scope 报告 |
诊断:连接与 scope 覆盖情况 | 诊断 |
下面按功能域拆解每个工具的参数与返回(全部以 IInstance.py 中注册的 input_schema 为准)。
2.1 事件读取
outlook_calendar_list_events(源码 IInstance.py#L185-L197)
- 必填参数:
start、end(ISO 8601 字符串,如'2026-08-11T00:00:00'); - 可选参数:
calendar(日历 id,缺省使用默认日历); - 走 Graph
calendarView端点,周期事件会被 Graph 展开为窗口内的单个 occurrence; - 单次最多返回
MAX_TOP = 100条(client.py#L41);当窗口内事件更多时返回next_link(Graph@odata.nextLink的续页 URL),否则为null—— 返回结构{events, next_link}。测试 test_outlook_calendar.py 验证了next_link的暴露与末页为None两种行为。
outlook_calendar_get_event(IInstance.py#L209-L214)
- 必填参数:
event_id; - 直接
GET /events/{id},返回经过清洗的事件对象。
2.2 事件写入(write 层级)
outlook_calendar_create_event(IInstance.py#L278-L286)
- 必填:
subject、start、end;可选:body(正文文本)、attendees(邮箱地址数组)、location(地点显示名)、calendar(目标日历 id,缺省默认日历); start/end有两种合法形态(见 schema 的oneOf):- 普通 ISO 字符串
'YYYY-MM-DDTHH:MM:SS'→ 自动包装为 UTC 的{dateTime, timeZone}; - 已成形对象
{dateTime, timeZone}→ 原样透传(例如传America/New_York时不会被强制改成 UTC);
- 普通 ISO 字符串
attendees会由 client.py#L70-L72 的attendee_list()映射为 Graph 收件人结构[{'emailAddress': {'address': e}, 'type': 'required'}, ...];- 邀请由 Graph 自己发出:
write层级门控的是 Graph 调用本身,不是独立的"发送邀请"步骤; - 测试 test_outlook_calendar.py#L154-L180 断言了 POST 到
/events、body 形状、UTC 包装、attendees 映射与 location 形状。
outlook_calendar_update_event(IInstance.py#L340-L366)
- 必填:
event_id;可选:subject、start、end、body、attendees、location; - PATCH 语义:只修改传入的字段,省略的字段保持不变;
attendees作为整体替换(Graph 会向新名单(重)发邀请/更新); - 若一个字段都没传,会抛出
ValueError: at least one field to update must be provided,避免产生空 PATCH。
outlook_calendar_delete_event(IInstance.py#L378-L385)
- 必填:
event_id;成功后返回{'deleted': event_id}。
outlook_calendar_respond(IInstance.py#L403-L414)
- 必填:
event_id、response(枚举值限定accept/decline/tentativelyAccept);可选:comment; - 请求路径为
/events/{id}/{response};测试验证了非法枚举被拒绝、合法枚举请求/events/e1/accept,以及readonly层级下被MicrosoftAccessError拦截(test_outlook_calendar.py#L197-L220)。
2.3 会议时间建议与忙闲查询
outlook_calendar_find_meeting_times(IInstance.py#L450-L469)
- 必填:
attendees(邮箱数组);可选:duration_minutes(默认 30,取值范围 5–480)、window_start、window_end; window_start与window_end必须成对出现,只传一个会被拒绝(测试 test_outlook_calendar.py#L237-L246);- 请求体:
attendees(映射后的收件人数组)、meetingDuration(ISO 8601 时长PT{duration}M)、可选的timeConstraint.timeslots; - 重要限制:
findMeetingTimes在 Microsoft 侧需要 delegated(已登录用户)上下文,app-only(client-credentials)认证下可能不被支持,会收到 Graph 错误。这是节点文档和 README 都明确标注的前提。
outlook_calendar_get_schedule(IInstance.py#L519-L530)
- 必填:
emails(邮箱数组)、start、end; POST /calendar/getSchedule,返回{'schedules': [...]};这是find_meeting_times在 app-only 场景下的替代方案。
2.4 日历管理
outlook_calendar_list_calendars(IInstance.py#L540-L546):无参数,GET /calendars,$top=100,返回清洗后的日历数组;outlook_calendar_create_calendar(IInstance.py#L558-L565):必填name,POST /calendars,需要 write 层级。
2.5 增量同步(delta sync)
outlook_calendar_delta_sync(IInstance.py#L598-L614)
- 首次调用传
start/end(ISO 8601 窗口),走GET /calendarView/delta?startDateTime=...&endDateTime=...; - 后续调用把上次返回的
delta_link传回,只拉取自上次以来的变更; - 返回
{events, delta_link, next_link}; - 测试验证了:携带
delta_link时直接 GET 该绝对 URL 而不是从 start/end 重建;首次调用使用startDateTime/endDateTime查询参数;三者都不传则报错(test_outlook_calendar.py#L262-L291)。
2.6 连接诊断
outlook_calendar_check_connection(IInstance.py#L152-L159)
- 做一次真实的
GET /calendar探测,并结合已授予的 OAuth scope 检查是否覆盖当前配置的 access tier; - 返回
connection_ok、access(tier)、requiredScopes,缺失时附missingScopes; - 官方使用指引:当任意日历操作报 scope 或权限错误时,先调用它定位问题。
三、在管道中接线:把工具挂到 Agent 上
节点文档给出了标准的 tool 节点接线方式:通过 control 指定 classType: "tool",并让 from 指向 agent 节点(Agent 同时需要配套的 memory 节点):
{
"id": "tool_outlook_calendar_1",
"provider": "tool_outlook_calendar",
"config": { "type": "tool_outlook_calendar" },
"control": [{ "classType": "tool", "from": "agent_rocketride_1" }]
}
接线完成后,Agent 会在其指令上下文中发现全部 outlook_calendar_* 工具并按需调用。服务注册元数据定义在 services.outlook_calendar.json:protocol: "tool_outlook_calendar://"、classType: ["tool"]、prefix: "outlook_calendar",其中 preconfig.default 给出了节点创建时的默认配置(authType: "service"、access: "write",其余凭据字段留空)。
四、配置参数与访问层级
节点文档的配置表如下(字段名按 RocketRide 的扁平化节点配置约定):
| 字段 | 必填 | 说明 |
|---|---|---|
microsoft.authType |
是 | service(Entra 应用,client credentials)或 user(OAuth) |
microsoft.tenantId / microsoft.clientId / microsoft.clientSecret |
service 时 |
Entra 应用注册凭据 |
microsoft.userPrincipalName |
service 时 |
操作者 UPN —— app-only 调用目标为 /users/{upn} |
microsoft.userToken |
user 时 |
由"登录"按钮填充,broker 自动刷新 |
outlook_calendar.access |
否 | readonly 或 write(默认)。由共享的 OUTLOOK_CALENDAR AccessSpec 解析,scope 从不手工填写 |
4.1 访问层级 → Graph scope 映射
定义在 microsoft_access.py#L178-L183 的 OUTLOOK_CALENDAR = AccessSpec(...):
| 层级 | 请求的 Graph scope | 能力 |
|---|---|---|
readonly |
Calendars.Read |
仅列表/读取事件与日历、会议时间建议、忙闲日程、delta-sync |
write(默认) |
Calendars.ReadWrite |
readonly 全部能力 + 创建/更新/删除事件、回复邀请、创建日历 |
4.2 层级是如何强制生效的
在节点生命周期里(共享基类 IGlobal.py 的 beginGlobal),配置会被 resolve_microsoft_access(cfg, spec) 解析为一个不可变的 MicrosoftAccess 对象(tier、scopes、can_write、flags)。每个写工具在发起请求前调用 self.IGlobal.access.require_write(op):
- 若节点是
readonly,任何写工具都会抛出MicrosoftAccessError(如"...needs write access, but this node is read-only (access='readonly')..."),提示提升 access 层级; - 测试 test_outlook_calendar.py#L143-L150 正是用
readonly层级验证create_event被拦截。
同时 validateConfig 在保存配置时就会校验 tier 合法性(未知 tier、非布尔 flag 都会告警),并把 scope 覆盖检查与运行时检查统一到 token_scope_report 上,避免三处检查漂移。
五、凭据获取:Entra 应用注册与用户 OAuth
节点文档说明:在 Entra admin center(entra.microsoft.com → App registrations)注册应用,授予 Graph 的 Calendars.Read 和/或 Calendars.ReadWrite 权限(service 用 application permission,user 用 delegated permission),并完成管理员同意。完整的微软 365 工具服务共享配置教程见仓库内的 docs/docusaurus/apps/vscode/microsoft-oauth.md,此处给出与 Outlook Calendar 直接相关的要点:
5.1 service(app-only,client credentials)
按 microsoft-oauth.md 的注册流程:
- 注册单租户应用;
- 添加 Microsoft Graph → Application permissions:
readonly层级授Calendars.Read,write层级授Calendars.ReadWrite(注意.All形式的 application permission 可满足同名 delegated scope 的检查); - 对租户执行管理员同意(application permission 是租户级的,应用无法自我同意);
- 创建 client secret 并立即复制;
- 节点配置填入
microsoft.authType: "service"、tenantId、clientId、clientSecret、userPrincipalName。
userPrincipalName 的作用非常关键:application permission 本身不限定邮箱/日历,节点的每个 Graph 调用都指向 /users/{userPrincipalName}(见 graph_client.py#L453-L462 的 user_base()),因此它决定了 app-only 凭据"操作谁的数据"。如需在 Microsoft 365 侧进一步收紧 app 的触达范围(如用 Exchange Online 的 New-ApplicationAccessPolicy 把应用权限限制到特定邮箱安全组),应在 Entra/Exchange 侧配置,而非在 RocketRide 里配置。
5.2 user(用户 OAuth)
microsoft.authType: "user" 时,节点配置面板的"登录"按钮(microsoft.oAuthButton)会把 microsoft.userToken 写入节点配置。该 token 由 RocketRide 的 OAuth broker 自动刷新:broker 授予身份 scope(openid email profile)外加恰好等于所选层级的 Graph scopes(最小权限原则),授权后的 scope 固定在同意时刻;如果事后把 outlook_calendar.access 从 readonly 提升到 write,需要断开并重新连接账户以重新同意新的 scope。
5.3 安全底线
- 绝不把凭据提交到仓库;使用节点配置(加密存储)或 Entra 应用 secret 轮换;
- 运行时 token 端点被白名单约束为 Microsoft 自己的
login.microsoftonline.com(graph_client.py#L179-L199),token 中携带的 broker 刷新 URL 必须是https且 host 属于受信 broker(内置oauth2.rocketride.ai/oauth.rocketride.ai,自托管可用环境变量RR_OAUTH_BROKER_URL追加),被篡改的存储 token 无法把凭据重定向到攻击者主机(graph_client.py#L145-L176)。
六、底层实现:共享 Graph 请求机制与安全边界
所有微软 365 工具服务(excel、word、onedrive、outlook mail、outlook calendar)都通过 graph_client.py 这"唯一一份"凭据与请求机制执行调用,outlook_calendar/client.py 通过 functools.partial 绑定(SERVICE = GraphService(product='Outlook Calendar', superset_scopes={'Calendars.ReadWrite'}),client.py#L35)。理解它有助于解释节点在真实 Graph 环境下的行为:
- 统一重试策略(
request(),graph_client.py#L465):429 与 5xx 指数退避,最多 4 次尝试(间隔 1s/2s/4s);429 对所有方法重试(Graph 未处理请求,重放安全),而 5xx 只对幂等方法(GET/HEAD/PUT/DELETE)重试——因为 POST 可能在报错前已被执行,重放可能重复创建事件/发送邀请;服务端Retry-After会被采纳并钳制在 0–30 秒内,防止 Graph 限流下发大数值把线程钉死; - 失败快速暴露:401/403 直接抛出
GraphError,错误信息点名 scope/application permission 与管理员同意(AADSTS65001表示需要同意);409/412 以冲突提示(文件在编辑期间被改动,需重读重试); - 绝对 URL 白名单:deltaLink / nextLink 这类调用方或 Graph 载荷带来的绝对 URL,只有
https且 host 为graph.microsoft.com时才允许携带 bearer token 发起(graph_client.py#L499-L509),凭据绝不会发往陌生主机; - 两种认证实现:
AppOnlyAuth(client-credentials,进程内缓存 token,在过期前 60 秒刷新,graph_client.py#L220)与BrokerUserAuth(broker 签发的用户 token,刷新协议为POST {oauth_server_url} {'refresh_token': ...}→200 {'access_token', 'expiry_date'},任何非 200、200 但缺 access_token、expiry 畸形都会被当作合约违约并 fail loud,graph_client.py#L284)。
七、响应清洗:Agent 友好的返回形状
Graph 原生的 event/calendar JSON 字段繁多,节点在返回前统一清洗成 Agent 真正需要的字段(client.py#L79-L138):
- 事件:
id、subject、start、end、isAllDay、isCancelled、seriesMasterId(周期系列的宿主 id)、recurrence、webLink、bodyPreview,外加展开的location(仅displayName)、organizer(邮箱对象)、attendees(邮箱 + 出席状态)、onlineMeeting(仅joinUrl); - 日历:
id、name、isDefaultCalendar、canEdit、owner(Graph 的 calendarowner本身已是emailAddress形态,故原样透传,与 event 的organizer深层嵌套不同,见 client.py#L126-L139 的注释); - 防漂移设计:
EVENT_SELECT/CALENDAR_SELECT这两个$select字符串由同一组字段元组拼接生成(client.py#L94-L97),保证"线上请求选哪些字段"与"返回清洗哪些字段"永远一致。
八、测试与可验证性
仓库为日历节点提供了专注的层级/请求形状测试 nodes/test/tool_microsoft_365/test_outlook_calendar.py(仅 mock HTTP 层 graph_client._urlopen,真实执行 IInstance 方法):
- readonly 拦截写工具:
create_event在 readonly 层级抛出MicrosoftAccessError; - 创建事件请求形状:POST 到
/events(或/calendars/{id}/events),body 含 UTC 包装的start/end、attendees邮箱映射、location; - respond 枚举校验:非法值拒绝、合法值请求
/events/e1/accept、readonly 拦截; - list_events 分页:
next_link存在与否两种分支; - find_meeting_times 窗口成对校验:只传
window_start或只传window_end都被拒绝且不发请求; - delta_sync:携带
delta_link时直接 GET 该 URL;首次调用带startDateTime/endDateTime参数; event_datetime助手:普通字符串包装为 UTC、已成形 dict 原样透传(非 UTC 时区不被覆盖)、其他类型拒绝;attendee_list助手:邮箱数组 → Graph 收件人形状。
九、常见问题排查
综合节点 README(outlook_calendar/README.md)与共享 README(tool_microsoft_365/README.md)的排查指引:
- scope / 403 错误:先调用
outlook_calendar_check_connection;若缺 scope,user认证下断开重连微软账户,service认证下补齐/同意 Entra 应用权限; access是readonly但写操作报错:每个写工具都会抛MicrosoftAccessError,把outlook_calendar.access提升到write;find_meeting_times在 app-only 认证下失败:该端点需要 delegated 上下文,改用userOAuth,或换用outlook_calendar_get_schedule获取忙闲信息;- 创建/更新事件的时区陷阱:需要非 UTC 时区时,
start/end传{dateTime, timeZone}对象而不是裸字符串(裸字符串一律按 UTC 处理); - 限流:限流按 Entra 应用/租户维度计算,节点对 429/5xx 自动指数退避重试。
十、适用前提与边界
- 节点操作的目标(event id、calendar id)永远是调用时参数,不是节点配置——这是所有微软 365 工具服务共享的设计约定;
service(app-only)认证下除findMeetingTimes外,其余工具均可工作;Calendars.ReadWrite这类 application permission 在租户内是全量的,收紧到特定邮箱需在 Exchange Online 侧用应用访问策略完成,RocketRide 本身只贯彻"作用于/users/{upn}"的约定;- 限流与 Microsoft 侧能力(如
findMeetingTimes的 delegated 要求)属于外部前提,节点通过清晰的错误信息与诊断工具帮你快速归因。
至此,你已经掌握了 tool_outlook_calendar 节点的完整能力面:11 个工具的调用方式与参数、readonly/write 层级与 Graph scope 的对应关系、tool 接线方法、Entra 凭据配置流程,以及底层共享 Graph 机制的可靠性设计。直接在 RocketRide 管道里把它接到 Agent 上,就能让 LLM 安全地代管 Outlook 日历的读写、邀约与同步。