Skip to main content

Calendar

View as Markdown

Exposes the Google Calendar API v3 as agent tools: list, get, create, update, move, quick-add, and delete events (including expanding recurring series into instances); query free/busy; manage calendars; and read/insert/delete access-control (ACL) rules.

What it does​

An agent-invocable tool node — no data flows through lanes. Each operation is a @tool_function an agent calls on demand. Operational targets (calendarId, eventId, ruleId) are always tool-call parameters, never node config; calendarId defaults to primary. Outputs are cleaned shapes (event id/status/start/end/attendees, calendar metadata, ACL rules, free/busy ranges), not raw API JSON.

Configuration​

FieldNotes
google.authTypeservice (service account) or user (OAuth).
google.serviceKey / google.adminEmailService account JSON key; adminEmail enables domain-wide delegation (impersonate that user).
google.oAuthButton / google.userTokenUser OAuth: sign in to populate the access token.
calendar.accessreadonly or write (default). Resolved by the shared CALENDAR spec in core/google_access.py; scopes are never hand-entered.
calendar.allowDeleteBoolean, default false. When off, event_delete and calendar_delete are refused even at the write tier. Enable only to permit permanent, irreversible deletion.
calendar.allowPublicSharingBoolean, default false. When off, acl_insert refuses rules that expose the calendar beyond individual grantees (scopeType default = anyone on the internet, domain = everyone in a domain). Grants to individual users/groups are not gated.

Access tiers → scopes​

TierScopeCapability
readonlycalendar.readonlyread events, calendars, ACLs, free/busy
writecalendarfull read/write (default)

Deletion (event_delete, calendar_delete) requires the write tier and calendar.allowDelete = true. The flag is off by default and, like gmail's allowHardDelete, is absent from the default profile (absent means false). Removing a sharing rule (acl_delete) is a write-tier operation and is not gated by allowDelete.

Tools​

  • Read events: event_list (with incremental sync — see below), event_get, event_instances (expand a recurring series), freebusy_query.
  • Read calendars/ACL: calendar_list, calendar_get, acl_list.
  • Write events: event_create, event_update (partial / patch semantics), event_move, event_quick_add (natural-language).
  • Write calendars/ACL: calendar_create, calendar_update (patch), acl_insert (share; scopeType default/domain additionally requires allowPublicSharing), acl_delete (unshare).
  • Delete (write + allowDelete): event_delete, calendar_delete.
  • Diagnostics: check_connection probes the Calendar API with a live call; for user OAuth it also verifies that granted scopes cover the configured access tier (service-account auth has no per-user scope grant to check).

Incremental sync (syncToken)​

event_list and calendar_list return a nextSyncToken on the last page of a fully-consumed listing. Store it, then pass it back as syncToken on the next call to receive only the events/calendars that changed since — the efficient way to keep a local view in sync. Do not combine syncToken with timeMin / timeMax / q. Paginate with nextPageToken until it is absent; the nextSyncToken appears on that final page.

Attendee invitations (sendUpdates)​

Event writes (event_create, event_update, event_move, event_quick_add, event_delete) take a sendUpdates parameter — all (default), externalOnly, or none. The node always sends it explicitly: Google's implicit default is none, which would silently skip notifying attendees. Sending invitations is normal write-tier behavior and is not gated separately — an agent with write access can invite attendees, so scope the node accordingly.

event_update accepts an empty description or location to clear that field. For acl_insert, scopeType must be user, group, domain, or default; default and domain rules require calendar.allowPublicSharing = true; the first three require scopeValue.

Setup​

Authenticate with either a Google service account (google.serviceKey JSON, optionally google.adminEmail for domain-wide delegation) or user OAuth (click sign-in to populate google.userToken). The Google Calendar API must be enabled on the Google Cloud project backing the credential.

Limits​

  • maxResults on listings is clamped to 1..250 (default 50); page with nextPageToken.
  • Free/busy queries return busy ranges per calendar plus any per-calendar errors (e.g. a calendar the credential cannot see).
  • Rate limits are per Google project; the node retries 429, rate-limit/quota 403, and 5xx responses with exponential backoff.

Examples​

An agent finds a free slot, then books it and invites a guest:

freebusy_query  { "timeMin": "2026-07-11T09:00:00Z", "timeMax": "2026-07-11T17:00:00Z",
                  "calendarIds": ["primary"] }
event_create    { "summary": "Design sync", "start": {"dateTime": "2026-07-11T14:00:00Z"},
                  "end": {"dateTime": "2026-07-11T15:00:00Z"},
                  "attendees": [{"email": "sam@example.com"}] }

Upstream docs​

Troubleshooting​

  • Scope / 403 errors: call check_connection; if scopes are missing, disconnect and reconnect the Google account at the required access tier.
  • access is read-only: write operations raise GoogleAccessError; raise calendar.access to write.
  • Delete refused at write tier: event_delete / calendar_delete also need calendar.allowDelete = true; it is off by default.
  • Attendees not notified: pass sendUpdates: "all" (the node's default) — none suppresses invitations.
Last updated on