@voltagent/core 2.2.1 → 2.2.2

package/docs/actions-triggers-docs/actions/airtable.md

@@ -0,0 +1,142 @@
+# Airtable Actions
+
+Airtable is one of the most common destinations for agent output—customer records, research notes,
+summaries, etc. VoltOps ships managed Airtable actions so you can create, update, delete, list, and
+fetch records without touching the Airtable REST API directly.
+
+## Prerequisites
+
+1. An Airtable base + table you want to write to.
+2. A Volt project (free or paid) with API keys (`pk_…`, `sk_…`).
+3. An Airtable credential inside Volt:
+   - Go to **Settings → Integrations → Add Credential → Airtable**.
+   - Paste your Airtable access token and save. Volt generates a `cred_xxx` identifier.
+4. (Recommended) Base and table IDs stored as environment variables:
+
+```bash
+AIRTABLE_CREDENTIAL_ID=cred_xxx
+AIRTABLE_BASE_ID=appxxxxxxxxxxxxxx
+AIRTABLE_TABLE_ID=tblxxxxxxxxxxxxxx
+```
+
+## Running Airtable actions from code
+
+```ts
+import { VoltOpsClient } from "@voltagent/core";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+await voltops.actions.airtable.createRecord({
+  credential: { credentialId: process.env.AIRTABLE_CREDENTIAL_ID! },
+  baseId: process.env.AIRTABLE_BASE_ID!,
+  tableId: process.env.AIRTABLE_TABLE_ID!,
+  fields: {
+    Name: "Ada Lovelace",
+    Role: "Researcher",
+    Status: "Ready",
+  },
+});
+
+// No stored credential? Pass your access token inline instead
+await voltops.actions.airtable.createRecord({
+  credential: { apiKey: process.env.AIRTABLE_API_KEY! },
+  baseId: process.env.AIRTABLE_BASE_ID!,
+  tableId: process.env.AIRTABLE_TABLE_ID!,
+  fields: {
+    Name: "Grace Hopper",
+  },
+});
+```
+
+Every call appears in Volt → **Actions** with request/response payloads, so you can monitor failures
+or re-run a specific payload without redeploying code.
+
+## Treat Airtable actions as tools
+
+The [`with-voltagent-actions`](https://github.com/voltagent/voltagent/tree/main/examples/with-voltagent-actions)
+example demonstrates how to expose each Airtable action as a VoltAgent tool. Below is a simplified
+version of the **Create Record** tool; the example repo includes create/update/delete/get/list
+variants plus a UI drawer inside the Volt console to test payloads.
+
+```ts
+import { createTool } from "@voltagent/core";
+import { VoltOpsClient } from "@voltagent/core";
+import { z } from "zod";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+export const createAirtableRecordTool = createTool({
+  name: "createAirtableRecord",
+  description: "Create a CRM row inside Airtable",
+  parameters: z.object({
+    fields: z.record(z.unknown()),
+    baseId: z.string().optional(),
+    tableId: z.string().optional(),
+  }),
+  execute: async ({ fields, baseId, tableId }) => {
+    const result = await voltops.actions.airtable.createRecord({
+      credential: { credentialId: process.env.AIRTABLE_CREDENTIAL_ID! },
+      baseId: baseId ?? process.env.AIRTABLE_BASE_ID!,
+      tableId: tableId ?? process.env.AIRTABLE_TABLE_ID!,
+      fields,
+      typecast: true,
+    });
+
+    return {
+      actionId: result.actionId,
+      metadata: result.metadata,
+      record: result.responsePayload,
+    };
+  },
+});
+```
+
+Add the tool to an agent:
+
+```ts
+const airtableAgent = new Agent({
+  name: "Airtable Assistant",
+  model: openai("gpt-4o-mini"),
+  instructions: "Use the Airtable tools to manage the operations database.",
+  tools: [createAirtableRecordTool, listAirtableRecordsTool, updateAirtableRecordTool],
+});
+```
+
+Now the agent can plan/tool-call requests like:
+
+```
+User: "Add Ada Lovelace to the workspace table and show me the latest 5 entries."
+```
+
+The planner will call `createAirtableRecord` followed by `listAirtableRecords`, and VoltOps will log
+both action runs.
+
+## Testing payloads in the console
+
+While building, open **Volt Console → Actions → Add Action** and select Airtable. The drawer mirrors
+the trigger UX with a credential step, configuration step (base/table dropdowns), and a **Payload &
+Test** editor. Enter any JSON payload and click **Run Test**; successful responses include a
+copy-pasteable SDK snippet, while errors display the raw provider message (e.g.,
+`INVALID_VALUE_FOR_COLUMN`).
+
+This makes it easy to iterate on Airtable data types before committing changes to an agent.
+
+## Troubleshooting
+
+- **Proxy/credential mismatch** – make sure the Volt credential uses the same service (case
+  sensitive). E.g., a credential named “airtable” must be attached to an Airtable action.
+- **Column IDs vs names** – use `returnFieldsByFieldId: true` if you prefer Airtable field IDs; the
+  default returns user-friendly names.
+- **Pagination** – `listRecords` accepts `pageSize`, `offset`, `view`, `filterByFormula`, and `sort`
+  parameters identical to Airtable’s REST API. VoltOps just forwards them.
+- **Observability** – check **Volt → Actions → Runs** to inspect payloads, metadata, retries, and
+  provider errors (`INVALID_PERMISSIONS_OR_MODEL_NOT_FOUND`, etc.).
+
+With VoltOps Actions you can keep agent logic focused on reasoning while Volt handles the last-mile
+integration to Airtable.

package/docs/actions-triggers-docs/actions/discord.md

@@ -0,0 +1,142 @@
+# Discord Actions
+
+Use Discord actions to announce deploys, coordinate incidents, or manage guild resources without
+touching the Discord REST API. VoltOps supports bot-token actions for full control plus a lightweight
+webhook action for simple notifications.
+
+## Prerequisites
+
+1. Discord application with a bot token. Invite the bot to the guild(s) you plan to use and grant
+   permissions for the actions you need (Send Messages, Manage Channels, Manage Roles, Add
+   Reactions, etc.).
+2. (Optional) Discord incoming webhook URL if you only need to post messages via webhook.
+3. A Volt project with API keys (`pk_…`, `sk_…`).
+4. Discord credential inside Volt: **Settings → Integrations → Add Credential → Discord**, then pick
+   **Bot Token** or **Webhook** and save. Volt generates a `cred_xxx` identifier.
+5. (Recommended) Store defaults as environment variables:
+
+```bash
+DISCORD_CREDENTIAL_ID=cred_bot_xxx
+DISCORD_WEBHOOK_CREDENTIAL_ID=cred_webhook_xxx
+DISCORD_DEFAULT_GUILD_ID=123456789012345678
+DISCORD_DEFAULT_CHANNEL_ID=123456789012345678
+DISCORD_DEFAULT_THREAD_ID=987654321098765432
+```
+
+## Available actions
+
+- `discord.sendMessage` / `discord.sendWebhookMessage`
+- `discord.deleteMessage`, `discord.getMessage`, `discord.listMessages`
+- `discord.reactToMessage`, `discord.removeReaction`
+- `discord.createChannel`, `discord.updateChannel`, `discord.deleteChannel`
+- `discord.getChannel`, `discord.listChannels`
+- `discord.listMembers`
+- `discord.addMemberRole`, `discord.removeMemberRole`
+
+Message + channel actions require a bot token; webhook messages only require a webhook credential.
+
+## Running Discord actions from code
+
+```ts
+import { VoltOpsClient } from "@voltagent/core";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+// Send a rich message with the bot token
+await voltops.actions.discord.sendMessage({
+  credential: { credentialId: process.env.DISCORD_CREDENTIAL_ID! },
+  guildId: process.env.DISCORD_DEFAULT_GUILD_ID!,
+  channelId: process.env.DISCORD_DEFAULT_CHANNEL_ID!,
+  content: "Deploy finished ✅",
+  embeds: [
+    {
+      title: "Artifact",
+      url: "https://example.com/deploy/123",
+      description: "Shipped by VoltAgent",
+    },
+  ],
+});
+
+// Send via webhook (no bot token required)
+await voltops.actions.discord.sendWebhookMessage({
+  credential: { credentialId: process.env.DISCORD_WEBHOOK_CREDENTIAL_ID! },
+  content: "New signup from landing page!",
+  username: "VoltAgent Bot",
+  threadId: process.env.DISCORD_DEFAULT_THREAD_ID ?? undefined,
+});
+
+// React to a message
+await voltops.actions.discord.reactToMessage({
+  credential: { credentialId: process.env.DISCORD_CREDENTIAL_ID! },
+  channelId: process.env.DISCORD_DEFAULT_CHANNEL_ID!,
+  messageId: "112233445566778899",
+  emoji: "eyes",
+});
+
+// Assign a role
+await voltops.actions.discord.addMemberRole({
+  credential: { credentialId: process.env.DISCORD_CREDENTIAL_ID! },
+  guildId: process.env.DISCORD_DEFAULT_GUILD_ID!,
+  userId: "999888777666555444",
+  roleId: "444555666777888999",
+});
+```
+
+## Treat Discord actions as tools
+
+```ts
+import { createTool } from "@voltagent/core";
+import { VoltOpsClient } from "@voltagent/core";
+import { z } from "zod";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+export const sendDiscordUpdate = createTool({
+  name: "sendDiscordUpdate",
+  description: "Send a Discord message to a channel or thread.",
+  parameters: z.object({
+    content: z.string().describe("Plain-text body"),
+    channelId: z.string().optional(),
+    threadId: z.string().optional(),
+  }),
+  execute: async ({ content, channelId, threadId }) => {
+    return await voltops.actions.discord.sendMessage({
+      credential: { credentialId: process.env.DISCORD_CREDENTIAL_ID! },
+      guildId: process.env.DISCORD_DEFAULT_GUILD_ID!,
+      channelId: channelId ?? process.env.DISCORD_DEFAULT_CHANNEL_ID!,
+      threadId: threadId ?? undefined,
+      content,
+    });
+  },
+});
+```
+
+Tools make it easy for an agent to narrate progress, open a new channel for an incident, or react to
+messages during planning.
+
+## Testing payloads in the console
+
+- Open **Volt Console → Actions → Add Action** and select the Discord action (bot or webhook).
+- Attach the correct credential type. Bot-token actions will also show guild/channel defaults you can
+  pre-fill.
+- Enter the payload (content, embeds, components, IDs) in **Payload & Test** and run it. Successful
+  responses display the raw Discord payload plus an SDK snippet.
+- Use console runs to capture message IDs for follow-up reactions, deletes, or replies.
+
+## Troubleshooting
+
+- 403/`Missing Permissions` errors usually mean the bot lacks the required permission (Send Messages,
+  Manage Channels/Roles) or is not in the guild.
+- Use a webhook credential only for `discord.sendWebhookMessage`; other actions require a bot token.
+- Provide `content`, `embeds`, or `components`—Discord rejects empty messages.
+- `emoji` should be an emoji name (`thumbsup`) or custom emoji syntax (`name:id`). Colons are
+  optional.
+- Channel, thread, and guild IDs must all belong to the guild your bot can access; mismatches return
+  404 errors.
+- Check **Volt → Actions → Runs** for payloads, metadata, and provider error messages when debugging.

package/docs/actions-triggers-docs/actions/gmail.md

@@ -0,0 +1,134 @@
+# Gmail Actions
+
+Send, reply, search, and fetch Gmail messages with VoltOps-managed actions—no MIME hand-crafting or
+token juggling required.
+
+## Prerequisites
+
+1. Gmail API enabled for your Google project plus either:
+   - OAuth2 credential with `accessToken` + `refreshToken` + client ID/secret, or
+   - Service account with domain-wide delegation (client email, private key, and optional delegated
+     user).
+2. A Volt project with API keys (`pk_…`, `sk_…`).
+3. Gmail credential inside Volt: **Settings → Integrations → Add Credential → Gmail**, choose OAuth2
+   or Service Account, paste the values, and save. Volt returns a `cred_xxx` identifier.
+4. (Recommended) Environment variables:
+
+```bash
+GMAIL_CREDENTIAL_ID=cred_xxx
+```
+
+## Available actions
+
+- `gmail.sendEmail` – send mail with text/html bodies, CC/BCC, Reply-To, attachments, or save as a
+  draft (`draft: true`).
+- `gmail.replyToEmail` – reply using `threadId` or `inReplyTo` plus the same fields as send.
+- `gmail.searchEmail` – search mailbox by query, sender/recipient, label, category, or timestamp
+  filters.
+- `gmail.getEmail` – fetch a single message by `messageId` (formats: `full`, `minimal`, `raw`,
+  `metadata`).
+- `gmail.getThread` – fetch an entire thread by `threadId`.
+
+## Running Gmail actions from code
+
+```ts
+import { VoltOpsClient } from "@voltagent/core";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+// Send an email
+await voltops.actions.gmail.sendEmail({
+  credential: { credentialId: process.env.GMAIL_CREDENTIAL_ID! },
+  to: ["teammate@example.com"],
+  cc: ["manager@example.com"],
+  subject: "Incident update",
+  htmlBody: "<p>All systems nominal.</p>",
+  textBody: "All systems nominal.",
+  replyTo: ["noreply@example.com"],
+  attachments: [
+    {
+      filename: "notes.txt",
+      content: Buffer.from("postmortem draft").toString("base64"),
+      contentType: "text/plain",
+    },
+  ],
+});
+
+// Reply inside an existing thread
+await voltops.actions.gmail.replyToEmail({
+  credential: { credentialId: process.env.GMAIL_CREDENTIAL_ID! },
+  to: ["teammate@example.com"],
+  subject: "Re: Incident update",
+  textBody: "Thanks for the quick fix.",
+  threadId: "188b6c3a3d9a1a2b",
+  inReplyTo: "<message-id@example.com>",
+});
+
+// Search and hydrate results
+const search = await voltops.actions.gmail.searchEmail({
+  credential: { credentialId: process.env.GMAIL_CREDENTIAL_ID! },
+  query: "from:alerts@example.com after:1719700000",
+  maxResults: 5,
+});
+
+// Fetch a message directly
+await voltops.actions.gmail.getEmail({
+  credential: { credentialId: process.env.GMAIL_CREDENTIAL_ID! },
+  messageId: "188b6c3a3d9a1a2b",
+  format: "full",
+});
+```
+
+## Treat Gmail actions as tools
+
+```ts
+import { createTool } from "@voltagent/core";
+import { VoltOpsClient } from "@voltagent/core";
+import { z } from "zod";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+export const sendGmailSummary = createTool({
+  name: "sendGmailSummary",
+  description: "Email a summary to a stakeholder.",
+  parameters: z.object({
+    to: z.string().email(),
+    subject: z.string(),
+    body: z.string(),
+  }),
+  execute: async ({ to, subject, body }) => {
+    return await voltops.actions.gmail.sendEmail({
+      credential: { credentialId: process.env.GMAIL_CREDENTIAL_ID! },
+      to,
+      subject,
+      textBody: body,
+    });
+  },
+});
+```
+
+Agents can now send follow-ups, reply in an existing thread, or fetch a message body as part of a
+reasoning chain.
+
+## Testing payloads in the console
+
+- Open **Volt Console → Actions → Add Action → Gmail** and attach your Gmail credential.
+- Pick the action, enter the payload (recipients, body, attachments), and run a test. Successful runs
+  show Gmail’s response plus an SDK snippet you can copy.
+- Set `draft: true` to create a draft without sending—useful while validating payloads.
+
+## Troubleshooting
+
+- `invalid_grant` or auth failures usually mean the refresh token is missing/expired or the OAuth
+  app lacks offline access; re-authorize and store the new token.
+- Service accounts require domain-wide delegation and a subject email if you are sending on behalf of
+  a user.
+- Provide at least one of `htmlBody` or `textBody`; replies also need `threadId` or `inReplyTo`.
+- Attachments must be base64-encoded content (no data URLs); include `contentType` when possible.
+- Inspect **Volt → Actions → Runs** for request/response bodies, retries, and Gmail error messages.

package/docs/actions-triggers-docs/actions/google-calendar.md

@@ -0,0 +1,145 @@
+# Google Calendar Actions
+
+Create, update, search, and delete Calendar events via VoltOps-managed actions—no webhook plumbing or
+manual OAuth handling.
+
+## Prerequisites
+
+1. Google Calendar API enabled plus OAuth2 credentials (Volt managed app or your own). Provide
+   `accessToken` + `refreshToken` + client ID/secret, or pass a valid short-lived `accessToken`.
+2. A Volt project with API keys (`pk_…`, `sk_…`).
+3. Google Calendar credential in Volt: **Settings → Integrations → Add Credential → Google
+   Calendar**, paste your OAuth values, and copy the returned `cred_xxx`.
+4. (Recommended) Environment variables:
+
+```bash
+GOOGLE_CALENDAR_CREDENTIAL_ID=cred_xxx
+```
+
+## Available actions
+
+- `calendar.createEvent` – create an event with attendees, reminders, locations, and time zones.
+- `calendar.updateEvent` – patch an event’s summary, times, attendees, description, status, or
+  location.
+- `calendar.deleteEvent` – remove an event by `eventId`.
+- `calendar.listEvents` – list events for a calendar with time windows, pagination, ordering, and
+  query.
+- `calendar.getEvent` – fetch a specific event by `eventId`.
+
+## Running Google Calendar actions from code
+
+```ts
+import { VoltOpsClient } from "@voltagent/core";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+// Create an event on the primary calendar
+await voltops.actions.googlecalendar.createEvent({
+  credential: { credentialId: process.env.GOOGLE_CALENDAR_CREDENTIAL_ID! },
+  calendarId: "primary",
+  summary: "Team sync",
+  description: "Weekly sync-up with the team",
+  location: "Video",
+  start: {
+    dateTime: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
+    timeZone: "UTC",
+  },
+  end: {
+    dateTime: new Date(Date.now() + 2 * 60 * 60 * 1000).toISOString(),
+    timeZone: "UTC",
+  },
+  attendees: [{ email: "teammate@example.com" }],
+});
+
+// Update an existing event
+await voltops.actions.googlecalendar.updateEvent({
+  credential: { credentialId: process.env.GOOGLE_CALENDAR_CREDENTIAL_ID! },
+  calendarId: "primary",
+  eventId: "event_123",
+  summary: "Updated team sync",
+  description: "Add roadmap review",
+});
+
+// List upcoming events
+const events = await voltops.actions.googlecalendar.listEvents({
+  credential: { credentialId: process.env.GOOGLE_CALENDAR_CREDENTIAL_ID! },
+  calendarId: "primary",
+  timeMin: new Date().toISOString(),
+  timeMax: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+  singleEvents: true,
+  orderBy: "startTime",
+  maxResults: 10,
+});
+
+// Fetch a specific event
+await voltops.actions.googlecalendar.getEvent({
+  credential: { credentialId: process.env.GOOGLE_CALENDAR_CREDENTIAL_ID! },
+  calendarId: "primary",
+  eventId: "event_123",
+});
+```
+
+## Treat Calendar actions as tools
+
+```ts
+import { Agent, createTool, VoltOpsClient } from "@voltagent/core";
+import { openai } from "@ai-sdk/openai";
+import { z } from "zod";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+export const scheduleMeetingTool = createTool({
+  name: "scheduleMeeting",
+  description: "Create a meeting on the primary Google Calendar.",
+  parameters: z.object({
+    summary: z.string(),
+    description: z.string().optional(),
+    start: z.string().describe("ISO date string"),
+    end: z.string().describe("ISO date string"),
+    attendees: z.array(z.string().email()).optional(),
+    timeZone: z.string().optional(),
+  }),
+  execute: async ({ summary, description, start, end, attendees, timeZone }) => {
+    return await voltops.actions.googlecalendar.createEvent({
+      credential: { credentialId: process.env.GOOGLE_CALENDAR_CREDENTIAL_ID! },
+      calendarId: "primary",
+      summary,
+      description,
+      start: { dateTime: start, timeZone: timeZone ?? "UTC" },
+      end: { dateTime: end, timeZone: timeZone ?? "UTC" },
+      attendees: attendees?.map((email) => ({ email })),
+    });
+  },
+});
+
+const calendarAgent = new Agent({
+  name: "Calendar Assistant",
+  model: openai("gpt-4o-mini"),
+  instructions: "Use Google Calendar tools to schedule and manage events.",
+  tools: [scheduleMeetingTool],
+});
+```
+
+Agents can now schedule meetings, modify them, or read back details inside reasoning chains.
+
+## Testing payloads in the console
+
+- Open **Volt Console → Actions → Add Action → Google Calendar** and attach your credential.
+- Choose an action, enter the payload (`calendarId`, `summary`, `start`, `end`, etc.), and run a test.
+- Inspect the request/response plus the SDK snippet shown in **How to use**.
+
+## Troubleshooting
+
+- Auth failures usually mean a missing/expired refresh token or mismatched OAuth client redirect URI;
+  re-authorize with offline access.
+- Include `timeZone` on `start`/`end` to avoid defaulting to the calendar’s zone.
+- Use `calendarId: "primary"` when unsure which calendar the credential owns.
+- `listEvents` accepts `timeMin`, `timeMax`, `q`, `singleEvents`, `orderBy`, and pagination via
+  `pageToken`.
+- Check **Volt → Actions → Runs** for the Google API response if an action fails.

package/docs/actions-triggers-docs/actions/google-drive.md

@@ -0,0 +1,127 @@
+# Google Drive Actions
+
+VoltOps ships managed Google Drive actions so agents can list, download, upload, move, copy, delete,
+and share files without manually signing requests or refreshing OAuth tokens.
+
+## Prerequisites
+
+1. Google Drive API enabled plus OAuth2 credentials (Volt managed app or your own). Provide
+   `accessToken` + `refreshToken` + client ID/secret, or pass a valid short-lived `accessToken`.
+2. A Volt project with API keys (`pk_…`, `sk_…`).
+3. Google Drive credential inside Volt: **Settings → Integrations → Add Credential → Google Drive**,
+   paste your OAuth values, and copy the returned `cred_xxx`.
+4. (Recommended) Environment variables:
+
+```bash
+GOOGLE_DRIVE_CREDENTIAL_ID=cred_xxx
+```
+
+## Available actions
+
+- `drive.listFiles` – list files/folders with search (`q`), ordering, pagination, and `includeTrashed`.
+- `drive.getFileMetadata` – fetch metadata for a specific file.
+- `drive.downloadFile` – download file content (base64 + content type).
+- `drive.uploadFile` – upload binary or base64 content; supports parent folders.
+- `drive.createFolder` – create a folder.
+- `drive.moveFile` – move to a new parent (optionally remove previous parents).
+- `drive.copyFile` – duplicate a file into another folder and/or name.
+- `drive.deleteFile` – delete or move to trash depending on Drive settings.
+- `drive.shareFilePublic` – create a public link (anyone with link can view).
+
+## Running Google Drive actions from code
+
+```ts
+import { VoltOpsClient } from "@voltagent/core";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+// List recent non-folder files
+const list = await voltops.actions.googledrive.listFiles({
+  credential: { credentialId: process.env.GOOGLE_DRIVE_CREDENTIAL_ID! },
+  q: "mimeType != 'application/vnd.google-apps.folder' and trashed=false",
+  orderBy: "modifiedTime desc",
+  pageSize: 25,
+});
+
+// Download a file (base64)
+const download = await voltops.actions.googledrive.downloadFile({
+  credential: { credentialId: process.env.GOOGLE_DRIVE_CREDENTIAL_ID! },
+  fileId: "file_123",
+});
+const fileBuffer = Buffer.from(download.responsePayload.contentBase64, "base64");
+
+// Upload a text file (base64)
+await voltops.actions.googledrive.uploadFile({
+  credential: { credentialId: process.env.GOOGLE_DRIVE_CREDENTIAL_ID! },
+  name: "hello.txt",
+  mimeType: "text/plain",
+  parents: ["root"],
+  content: Buffer.from("Hello VoltAgent!").toString("base64"),
+  isBase64: true,
+});
+
+// Share a file publicly
+await voltops.actions.googledrive.shareFilePublic({
+  credential: { credentialId: process.env.GOOGLE_DRIVE_CREDENTIAL_ID! },
+  fileId: "file_123",
+});
+```
+
+Each method accepts either a stored `credentialId` or inline OAuth tokens
+(`accessToken` or `refreshToken` + `clientId` + `clientSecret`).
+
+## Treat Drive actions as tools
+
+```ts
+import { Agent, createTool, VoltOpsClient } from "@voltagent/core";
+import { openai } from "@ai-sdk/openai";
+import { z } from "zod";
+
+const voltops = new VoltOpsClient({
+  publicKey: process.env.VOLTAGENT_PUBLIC_KEY!,
+  secretKey: process.env.VOLTAGENT_SECRET_KEY!,
+});
+
+export const shareDriveFile = createTool({
+  name: "shareDriveFile",
+  description: "Share a Drive file publicly and return the webViewLink.",
+  parameters: z.object({
+    fileId: z.string(),
+  }),
+  execute: async ({ fileId }) => {
+    const result = await voltops.actions.googledrive.shareFilePublic({
+      credential: { credentialId: process.env.GOOGLE_DRIVE_CREDENTIAL_ID! },
+      fileId,
+    });
+
+    return result.responsePayload;
+  },
+});
+
+const driveAgent = new Agent({
+  name: "Drive Assistant",
+  model: openai("gpt-4o-mini"),
+  instructions: "Use Google Drive to fetch or share files for the user.",
+  tools: [shareDriveFile],
+});
+```
+
+## Testing payloads in the console
+
+- Open **Volt Console → Actions → Add Action → Google Drive** and attach your credential.
+- Pick an action, enter the payload (`q`, `fileId`, `content`, etc.), and click **Run Test**.
+- Review the response plus the SDK snippet shown in **How to use**.
+
+## Troubleshooting
+
+- Auth errors usually mean a missing/expired refresh token or incorrect OAuth client setup;
+  re-authorize with offline access.
+- Service accounts must be added to the Drive or shared folders you target.
+- Set `isBase64: true` when sending base64 content; omit it when streaming binary buffers.
+- `listFiles` supports pagination with `pageToken`, filtering with `q`, and excluding trash via
+  `includeTrashed: false`.
+- Public sharing grants anyone-with-link viewer access; use Drive’s native sharing for finer control.
+- Inspect **Volt → Actions → Runs** for the Google API request/response if an action fails.