VoltAgent Google Drive 触发器实战基于轮询的 Drive 文件变更驱动 Agent 自动化【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址: https://gitcode.com/gh_mirrors/vo/voltagentGoogle Drive 触发器是 VoltAgent 自动化体系中面向存储场景的核心入口之一。它通过轮询Polling方式持续监听 Google Drive 中的文件与文件夹变更并在检测到创建或更新事件时自动启动你绑定的 Agent 或工作流让文件一上传、Agent 立刻处理成为开箱即用的能力。读完本文你将掌握 Google Drive 触发器的 OAuth 2.0 凭证配置、触发参数与事件类型、载荷结构以及如何在 VoltOps Console 中把触发器绑定到 Agent 目标并完成端到端激活验证同时理解其在 VoltAgent 核心源码中的目录注册与事件分发机制。触发器能解决什么问题在典型的 AI Agent 工作流中文件往往是最常见的事件源用户上传 PDF、团队共享文件夹出现新素材、系统定时导出报表……如果这些场景都靠手动触发 Agent效率和实时性都难以保证。Google Drive 触发器正是为此设计处理新上传的 PDF、图片或文档文件落盘即触发 Agent 做解析、摘要或转写把文件夹变更镜像到其他系统新增文件后自动同步到数据库、CMS 或消息平台对新文件运行分类或信息抽取按 MIME 类型过滤只处理感兴趣的格式监控共享团队文件夹成员新增或更新内容时自动跟进。与 Webhook 方案不同VoltOps 云端负责 OAuth 托管、令牌自动刷新与轮询窗口管理你无需搭建回调端点、维护令牌过期逻辑也不必关心 Webhook 订阅的复杂管道工程plumbing即可对文件新增或更新这类事件做出响应。工作方式轮询架构与目录注册在 VoltAgent 中Google Drive 属于Storage分类下的轮询型deliveryModes: [polling]触发器认证方式为 OAuth 2.0authType: oauth2。这一元信息定义在核心包的默认触发器目录中default-trigger-catalog.ts{ triggerId: google-drive, dslTriggerId: google-drive, displayName: Google Drive, service: GoogleDrive, category: Storage, authType: oauth2, deliveryModes: [polling], ... events: [ { key: googledrive.fileChanged, displayName: File created or updated, ... }, { key: googledrive.folderChanged, displayName: Folder content changed, ... }, ], }可以看到每个事件都带有默认配置defaultConfig其中provider.type为googledrivetriggerType为fileChanged或folderChanged默认轮询间隔为pollIntervalSeconds: 60。目录构建逻辑在 catalog.ts 中会把形如googledrive.fileChanged的事件键转换为默认 HTTP 路径/triggers/googledrive/fileChanged并在 dsl.ts 中通过createTriggers提供on.googleDrive.fileChanged(...)这样的点号链式注册语法——这正是你稍后会在 Agent 代码中写下的处理器入口。第一步配置 OAuth 2.0 凭证Google Drive 触发器使用 OAuth 2.0 进行授权。完整配置分四步在 Google Cloud 项目中启用 Google Drive API。在APIs Services → Credentials中创建OAuth client ID应用类型选择Web application。将 VoltOps Console 中显示的VoltOps OAuth redirect URL添加为授权重定向 URIAuthorized redirect URI。在 VoltOps Console 的Step 1 (Connection)中创建 Google Drive 凭证填入Client ID与Client Secret点击Authorize with Google完成 OAuth 授权流程。VoltOps 会请求https://www.googleapis.com/auth/drive作用域并在令牌过期后自动刷新。从源码看凭证类型在 types.ts 中被定义为VoltOpsGoogleDriveCredential包含accessToken、refreshToken、clientId、clientSecret、tokenType与expiresAt等字段既支持引用已存储的凭证VoltOpsStoredCredentialRef也支持携带完整 OAuth 元数据。在 actions/client.ts 中ensureGoogleDriveCredential会校验凭证必须包含credentialId、accessToken或refreshToken clientId clientSecret三者之一否则抛出VoltOpsActionError——这保证了后续轮询与动作执行时的凭证可用性。第二步触发器配置参数创建绑定Binding时你需要指定以下触发选项配置项说明建议 / 默认值Trigger TypefileChanged任意文件的更新/创建或folderChanged文件夹下的条目变更必选Folder ID可选将检测范围限定到某个具体文件夹folderChanged场景强烈建议填写MIME Type Filter可选需要匹配的 MIME 类型数组如[application/pdf, image/png]不填则匹配所有类型Polling IntervalVoltOps 轮询 Drive 的频率默认 60 秒最小 30 秒这些默认值同样固化在触发器目录的defaultConfig中folderId: null、matchMimeTypes: null、pollIntervalSeconds: 60意味着不显式配置时触发器会监听整个 Drive 的全部文件变化并保持 60 秒轮询节奏。生产环境建议使用folderChanged时务必指定Folder ID以缩小扫描范围、降低 API 调用量与事件噪音对高频目录可尝试将轮询间隔下调至 30 秒更低值会增加 Google Drive API 用量。第三步事件类型与载荷结构Google Drive 触发器提供两个事件交付方式均为轮询事件键含义交付方式googledrive.fileChanged文件被创建或更新Pollinggoogledrive.folderChanged配置的文件夹中有条目被添加或更新Polling当事件命中时VoltOps 会将变更文件的元数据连同 provider 上下文一并投递典型载荷如下{ provider: googledrive, triggerType: fileChanged, folderId: null, matchMimeTypes: [application/pdf], polledAt: 2024-11-14T10:00:00.000Z, fileId: 1AbCdEfGhIj, file: { id: 1AbCdEfGhIj, name: Quarterly-report.pdf, mimeType: application/pdf, parents: [root], modifiedTime: 2024-11-14T09:58:12.000Z, createdTime: 2024-11-14T09:57:01.000Z, webViewLink: https://drive.google.com/file/d/1AbCdEfGhIj/view } }字段解读provider/triggerType标识来源与本次触发类型用于在处理器中做路由分流folderId/matchMimeTypes回显触发绑定中的过滤配置便于 Agent 判断为什么触发polledAt本次轮询发现变更的时间戳fileGoogle Drive 文件对象核心元数据其中id可用于后续动作下载、移动、分享等webViewLink可直接用于生成通知链接parents给出父目录列表。从源码角度看这一载荷会被包装进 types.ts 定义的VoltOpsTriggerEnvelope包含provider、event、payload、bindingId、targetId等字段再投递到你的 Agent 端点处理器可从context.payload中直接取得上述文件信息。第四步在 Agent 中注册触发器处理器激活绑定的第一步是把触发器处理器代码加入你的 VoltAgent 项目。基于 dsl.ts 提供的类型安全 DSLGoogle Drive 的处理器写法如下import { VoltAgent, createTriggers } from voltagent/core; new VoltAgent({ triggers: createTriggers((on) { on.googleDrive.fileChanged(({ payload }) { console.log(Drive file changed:, payload.file?.name); // 在这里调用你的 Agent / 工作流处理逻辑 }); }), });createTriggers会为目录中每个已注册的 provider 生成代理对象on.googleDrive对应google-drive目录条目fileChanged/folderChanged则对应两个事件键见 catalog.ts 中eventKeyToProperty的驼峰转换规则若你写错事件名DSL 会直接抛出Trigger event not defined in the VoltOps catalog错误从编译期到运行期双重兜底。默认端点路径由事件键自动生成POST /triggers/googledrive/fileChangedfolderChanged事件对应POST /triggers/googledrive/folderChanged。当你为 VoltAgent 添加该处理器后服务会自动挂载对应路由接收来自 VoltOps 的触发请求。第五步添加 Target 激活绑定触发器本身不会执行任何逻辑必须添加目标Agent 或 Workflow才能激活绑定。完整流程与所有触发器 provider 一致详见 usage.mdAirtable 示例流程通用核心步骤包括Step 1 – Connection完成上文的 Google Drive OAuth 凭证配置Step 2 – Configuration选择 Trigger Type、Folder ID、MIME 过滤与轮询间隔创建 Draft 状态的绑定Step 3 – Add Target在向导中粘贴上述处理器代码并勾选Ive added the snippet to my project然后配置交付目标Agent Servers选择已注册的 Agent 服务器可新建填写名称与根 URLVolt Tunnels本地开发时运行pnpm volt tunnel 3141获取临时 HTTPS 地址如https://happy-cat-42.tunnel.voltagent.dev用于把本地 VoltAgent 暴露给 VoltOps 做联调Custom HTTPS URL自建 Webhook 端点可配 POST/PUT/PATCH 方法与自定义 Headers如X-API-Key。 端点路径保持默认的/triggers/googledrive/fileChanged并通过Test Connection验证可达性注意区分Endpoint is responding correctly / 404 Not Found / Connection failed三种结果Step 4 – Activate Test激活绑定后向监控的文件夹上传或修改一个文件等待一个轮询周期再到 VoltOps Console 的Agents页面查看触发执行历史图表确认 Agent 已被成功拉起。纵深触发器与 Drive 动作的组合使用触发器负责入站事件而将处理结果写回Drive 或其他 SaaS 系统时可配合 VoltAgent 的 Actions 能力见 actions/overview.md。Google Drive 动作在 actions/client.ts 中注册为client.googledrive.*一组方法与触发器共享同一套凭证体系与可观测性listFiles/getFile/downloadFile基于触发器载荷中的fileId拉取或下载文件内容uploadFile/createFolder把 Agent 产出文本、报告回传 DrivemoveFile/copyFile/deleteFile完成文件编排shareFile生成共享信息以便后续分发。典型链路为googledrive.fileChanged触发 → Agent 读取payload.file→ 下载并解析 → 通过googledrive.uploadFile写入结果目录。凭证校验统一走 executeGoogleDriveAction 与ensureGoogleDriveCredential保证触发与执行两端的授权上下文一致。小结Google Drive 触发器把文件即事件源的自动化变得轻量而可靠VoltOps 托管 OAuth 与令牌刷新轮询机制免去 Webhook 管道搭建fileChanged与folderChanged两个事件配合 MIME 过滤与 Folder ID 即可精准圈定监控范围绑定 目标的两段式激活流程与统一的交付通道Agent Servers / Volt Tunnels / Custom HTTPS URL则让上传即处理的 Agent 工作流快速落地。配合源码中 default-trigger-catalog.ts 的目录定义、dsl.ts 的类型安全注册语法与 types.ts 的凭证模型你可以完全掌控从事件捕获到 Agent 执行的全链路行为。【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址: https://gitcode.com/gh_mirrors/vo/voltagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 VoltAgent Google Drive 触发器实战：基于轮询的 Drive 文件变更驱动 Agent 自动化
VoltAgent Google Drive 触发器实战基于轮询的 Drive 文件变更驱动 Agent 自动化【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址: https://gitcode.com/gh_mirrors/vo/voltagentGoogle Drive 触发器是 VoltAgent 自动化体系中面向存储场景的核心入口之一。它通过轮询Polling方式持续监听 Google Drive 中的文件与文件夹变更并在检测到创建或更新事件时自动启动你绑定的 Agent 或工作流让文件一上传、Agent 立刻处理成为开箱即用的能力。读完本文你将掌握 Google Drive 触发器的 OAuth 2.0 凭证配置、触发参数与事件类型、载荷结构以及如何在 VoltOps Console 中把触发器绑定到 Agent 目标并完成端到端激活验证同时理解其在 VoltAgent 核心源码中的目录注册与事件分发机制。触发器能解决什么问题在典型的 AI Agent 工作流中文件往往是最常见的事件源用户上传 PDF、团队共享文件夹出现新素材、系统定时导出报表……如果这些场景都靠手动触发 Agent效率和实时性都难以保证。Google Drive 触发器正是为此设计处理新上传的 PDF、图片或文档文件落盘即触发 Agent 做解析、摘要或转写把文件夹变更镜像到其他系统新增文件后自动同步到数据库、CMS 或消息平台对新文件运行分类或信息抽取按 MIME 类型过滤只处理感兴趣的格式监控共享团队文件夹成员新增或更新内容时自动跟进。与 Webhook 方案不同VoltOps 云端负责 OAuth 托管、令牌自动刷新与轮询窗口管理你无需搭建回调端点、维护令牌过期逻辑也不必关心 Webhook 订阅的复杂管道工程plumbing即可对文件新增或更新这类事件做出响应。工作方式轮询架构与目录注册在 VoltAgent 中Google Drive 属于Storage分类下的轮询型deliveryModes: [polling]触发器认证方式为 OAuth 2.0authType: oauth2。这一元信息定义在核心包的默认触发器目录中default-trigger-catalog.ts{ triggerId: google-drive, dslTriggerId: google-drive, displayName: Google Drive, service: GoogleDrive, category: Storage, authType: oauth2, deliveryModes: [polling], ... events: [ { key: googledrive.fileChanged, displayName: File created or updated, ... }, { key: googledrive.folderChanged, displayName: Folder content changed, ... }, ], }可以看到每个事件都带有默认配置defaultConfig其中provider.type为googledrivetriggerType为fileChanged或folderChanged默认轮询间隔为pollIntervalSeconds: 60。目录构建逻辑在 catalog.ts 中会把形如googledrive.fileChanged的事件键转换为默认 HTTP 路径/triggers/googledrive/fileChanged并在 dsl.ts 中通过createTriggers提供on.googleDrive.fileChanged(...)这样的点号链式注册语法——这正是你稍后会在 Agent 代码中写下的处理器入口。第一步配置 OAuth 2.0 凭证Google Drive 触发器使用 OAuth 2.0 进行授权。完整配置分四步在 Google Cloud 项目中启用 Google Drive API。在APIs Services → Credentials中创建OAuth client ID应用类型选择Web application。将 VoltOps Console 中显示的VoltOps OAuth redirect URL添加为授权重定向 URIAuthorized redirect URI。在 VoltOps Console 的Step 1 (Connection)中创建 Google Drive 凭证填入Client ID与Client Secret点击Authorize with Google完成 OAuth 授权流程。VoltOps 会请求https://www.googleapis.com/auth/drive作用域并在令牌过期后自动刷新。从源码看凭证类型在 types.ts 中被定义为VoltOpsGoogleDriveCredential包含accessToken、refreshToken、clientId、clientSecret、tokenType与expiresAt等字段既支持引用已存储的凭证VoltOpsStoredCredentialRef也支持携带完整 OAuth 元数据。在 actions/client.ts 中ensureGoogleDriveCredential会校验凭证必须包含credentialId、accessToken或refreshToken clientId clientSecret三者之一否则抛出VoltOpsActionError——这保证了后续轮询与动作执行时的凭证可用性。第二步触发器配置参数创建绑定Binding时你需要指定以下触发选项配置项说明建议 / 默认值Trigger TypefileChanged任意文件的更新/创建或folderChanged文件夹下的条目变更必选Folder ID可选将检测范围限定到某个具体文件夹folderChanged场景强烈建议填写MIME Type Filter可选需要匹配的 MIME 类型数组如[application/pdf, image/png]不填则匹配所有类型Polling IntervalVoltOps 轮询 Drive 的频率默认 60 秒最小 30 秒这些默认值同样固化在触发器目录的defaultConfig中folderId: null、matchMimeTypes: null、pollIntervalSeconds: 60意味着不显式配置时触发器会监听整个 Drive 的全部文件变化并保持 60 秒轮询节奏。生产环境建议使用folderChanged时务必指定Folder ID以缩小扫描范围、降低 API 调用量与事件噪音对高频目录可尝试将轮询间隔下调至 30 秒更低值会增加 Google Drive API 用量。第三步事件类型与载荷结构Google Drive 触发器提供两个事件交付方式均为轮询事件键含义交付方式googledrive.fileChanged文件被创建或更新Pollinggoogledrive.folderChanged配置的文件夹中有条目被添加或更新Polling当事件命中时VoltOps 会将变更文件的元数据连同 provider 上下文一并投递典型载荷如下{ provider: googledrive, triggerType: fileChanged, folderId: null, matchMimeTypes: [application/pdf], polledAt: 2024-11-14T10:00:00.000Z, fileId: 1AbCdEfGhIj, file: { id: 1AbCdEfGhIj, name: Quarterly-report.pdf, mimeType: application/pdf, parents: [root], modifiedTime: 2024-11-14T09:58:12.000Z, createdTime: 2024-11-14T09:57:01.000Z, webViewLink: https://drive.google.com/file/d/1AbCdEfGhIj/view } }字段解读provider/triggerType标识来源与本次触发类型用于在处理器中做路由分流folderId/matchMimeTypes回显触发绑定中的过滤配置便于 Agent 判断为什么触发polledAt本次轮询发现变更的时间戳fileGoogle Drive 文件对象核心元数据其中id可用于后续动作下载、移动、分享等webViewLink可直接用于生成通知链接parents给出父目录列表。从源码角度看这一载荷会被包装进 types.ts 定义的VoltOpsTriggerEnvelope包含provider、event、payload、bindingId、targetId等字段再投递到你的 Agent 端点处理器可从context.payload中直接取得上述文件信息。第四步在 Agent 中注册触发器处理器激活绑定的第一步是把触发器处理器代码加入你的 VoltAgent 项目。基于 dsl.ts 提供的类型安全 DSLGoogle Drive 的处理器写法如下import { VoltAgent, createTriggers } from voltagent/core; new VoltAgent({ triggers: createTriggers((on) { on.googleDrive.fileChanged(({ payload }) { console.log(Drive file changed:, payload.file?.name); // 在这里调用你的 Agent / 工作流处理逻辑 }); }), });createTriggers会为目录中每个已注册的 provider 生成代理对象on.googleDrive对应google-drive目录条目fileChanged/folderChanged则对应两个事件键见 catalog.ts 中eventKeyToProperty的驼峰转换规则若你写错事件名DSL 会直接抛出Trigger event not defined in the VoltOps catalog错误从编译期到运行期双重兜底。默认端点路径由事件键自动生成POST /triggers/googledrive/fileChangedfolderChanged事件对应POST /triggers/googledrive/folderChanged。当你为 VoltAgent 添加该处理器后服务会自动挂载对应路由接收来自 VoltOps 的触发请求。第五步添加 Target 激活绑定触发器本身不会执行任何逻辑必须添加目标Agent 或 Workflow才能激活绑定。完整流程与所有触发器 provider 一致详见 usage.mdAirtable 示例流程通用核心步骤包括Step 1 – Connection完成上文的 Google Drive OAuth 凭证配置Step 2 – Configuration选择 Trigger Type、Folder ID、MIME 过滤与轮询间隔创建 Draft 状态的绑定Step 3 – Add Target在向导中粘贴上述处理器代码并勾选Ive added the snippet to my project然后配置交付目标Agent Servers选择已注册的 Agent 服务器可新建填写名称与根 URLVolt Tunnels本地开发时运行pnpm volt tunnel 3141获取临时 HTTPS 地址如https://happy-cat-42.tunnel.voltagent.dev用于把本地 VoltAgent 暴露给 VoltOps 做联调Custom HTTPS URL自建 Webhook 端点可配 POST/PUT/PATCH 方法与自定义 Headers如X-API-Key。 端点路径保持默认的/triggers/googledrive/fileChanged并通过Test Connection验证可达性注意区分Endpoint is responding correctly / 404 Not Found / Connection failed三种结果Step 4 – Activate Test激活绑定后向监控的文件夹上传或修改一个文件等待一个轮询周期再到 VoltOps Console 的Agents页面查看触发执行历史图表确认 Agent 已被成功拉起。纵深触发器与 Drive 动作的组合使用触发器负责入站事件而将处理结果写回Drive 或其他 SaaS 系统时可配合 VoltAgent 的 Actions 能力见 actions/overview.md。Google Drive 动作在 actions/client.ts 中注册为client.googledrive.*一组方法与触发器共享同一套凭证体系与可观测性listFiles/getFile/downloadFile基于触发器载荷中的fileId拉取或下载文件内容uploadFile/createFolder把 Agent 产出文本、报告回传 DrivemoveFile/copyFile/deleteFile完成文件编排shareFile生成共享信息以便后续分发。典型链路为googledrive.fileChanged触发 → Agent 读取payload.file→ 下载并解析 → 通过googledrive.uploadFile写入结果目录。凭证校验统一走 executeGoogleDriveAction 与ensureGoogleDriveCredential保证触发与执行两端的授权上下文一致。小结Google Drive 触发器把文件即事件源的自动化变得轻量而可靠VoltOps 托管 OAuth 与令牌刷新轮询机制免去 Webhook 管道搭建fileChanged与folderChanged两个事件配合 MIME 过滤与 Folder ID 即可精准圈定监控范围绑定 目标的两段式激活流程与统一的交付通道Agent Servers / Volt Tunnels / Custom HTTPS URL则让上传即处理的 Agent 工作流快速落地。配合源码中 default-trigger-catalog.ts 的目录定义、dsl.ts 的类型安全注册语法与 types.ts 的凭证模型你可以完全掌控从事件捕获到 Agent 执行的全链路行为。【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址: https://gitcode.com/gh_mirrors/vo/voltagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考