Worlds / Comms and scheduling

Google Calendar API

A local Google Calendar with calendars, events, recurring series, attendees and room resources. Test the scheduling agent that books, moves and cancels meetings without breaking anyone else's day.

Base path: /calendar/v3
Auth: OAuth bearer token, the world key
Endpoints: 14
Status: Active today

This reference previews the surface the Google Calendar world serves in the closed beta. Paths mirror the public Google Calendar API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_GOOGLE_CALENDAR_URL`	This world's origin followed by `/calendar/v3`
`WORLDS_API_KEY`	The world key, accepted wherever Google Calendar expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · googleapis

import { google } from "googleapis";

const auth = new google.auth.OAuth2();
auth.setCredentials({ access_token: process.env.WORLDS_API_KEY });

const calendar = google.calendar({
  version: "v3",
  auth,
  rootUrl: process.env.WORLDS_GOOGLE_CALENDAR_URL,
});

const { data } = await calendar.events.list({ calendarId: "primary", maxResults: 10 });

API reference

14 of 14

Events

Meetings and appointments with attendees and reminders.

GET/calendar/v3/calendars/{calendarId}/eventsList events
POST/calendar/v3/calendars/{calendarId}/eventsCreate an event
GET/calendar/v3/calendars/{calendarId}/events/{eventId}Get an event
PATCH/calendar/v3/calendars/{calendarId}/events/{eventId}Update an event
DELETE/calendar/v3/calendars/{calendarId}/events/{eventId}Delete an event

Fields · 6

`id`	string	Event id
`summary`	string	Title
`start`	object	dateTime or date, and timeZone
`end`	object	dateTime or date, and timeZone
`attendees`	array	Attendees and their response
`status`	string	confirmed, tentative or cancelled

Calendars

Calendars a user owns or subscribes to.

GET/calendar/v3/users/me/calendarListList calendars
POST/calendar/v3/calendarsCreate a calendar
GET/calendar/v3/calendars/{calendarId}Get a calendar

Fields · 4

`id`	string	Calendar id
`summary`	string	Name
`timeZone`	string	Time zone
`accessRole`	string	owner, writer or reader

Free and busy

Availability across one or more calendars.

POST/calendar/v3/freeBusyQuery free and busy times
GET/calendar/v3/users/me/calendarList/{calendarId}Get a calendar's access role
GET/calendar/v3/calendars/{calendarId}/events?timeMin={t}List upcoming events to find gaps

Fields · 4

`timeMin`	datetime	Window start
`timeMax`	datetime	Window end
`items`	array	Calendar ids to check
`calendars`	object	Busy blocks per calendar

Calendar ACL

Who can see or edit a calendar.

GET/calendar/v3/calendars/{calendarId}/aclList sharing rules
POST/calendar/v3/calendars/{calendarId}/aclShare a calendar
DELETE/calendar/v3/calendars/{calendarId}/acl/{ruleId}Remove a sharing rule

Fields · 4

`id`	string	Rule id
`role`	string	none, freeBusyReader, reader, writer or owner
`scope`	object	Type and value of the grantee
`etag`	string	Version tag of the rule

Test workflow

Prepare. Select the Google Calendar setup for your workflow and review its starting records, including events, calendars, free and busy.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Only the Nov 3 standup instance moved
Weekly standup series unchanged
Vendor review on Wed 5 at 14:00 with no conflicts
Old sync canceled with updates sent
Friday out of office block untouched

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Google Calendar
version: 2
connector: google-calendar
seed: google-calendar-starter
mode: isolated
policy: >
  Dana is out Monday morning. Move only this Monday's standup to Tuesday
  09:00, move Vendor review to Wednesday afternoon, and cancel Old sync with a
  note to attendees.
tasks:
  - id: reschedule-a-single-meeting-around-a-conflict
    prompt: Reschedule a single meeting around a conflict
  - id: book-a-room-for-a-new-meeting-with-the-right-attendees
    prompt: Book a room for a new meeting with the right attendees
  - id: cancel-events-and-notify-attendees
    prompt: Cancel events and notify attendees
expected:
  - Only the Nov 3 standup instance moved
  - Weekly standup series unchanged
  - "Vendor review on Wed 5 at 14:00 with no conflicts"
  - Old sync canceled with updates sent
  - Friday out of office block untouched
scenarios:
  - rate-limited
  - stale-etag
  - sync-token-expired

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	events.insert returns 403 rateLimitExceeded
`stale-etag`	Updating with an old etag returns 412
`sync-token-expired`	A stale syncToken returns 410 and needs a full sync
`room-declined`	The room resource declines the booking
`duplicate-id`	Inserting an existing event id returns 409

Starting data

Start each run from the same records and relationships. The overview below describes the Google Calendar starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
calendars	40 user calendars and 8 room resources
events	500 events, single and recurring
attendees	Response status accepted, declined, tentative and needsAction
working hours	Working hours and time zones per user
out of office	OOO blocks for 4 users

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Events records

Events

Meetings and appointments with attendees and reminders.

Field	Type	Meaning / relationship
`id`	string	Event id
`summary`	string	Title
`start`	object	dateTime or date, and timeZone
`end`	object	dateTime or date, and timeZone
`attendees`	array	Attendees and their response
`status`	string	confirmed, tentative or cancelled

json · illustrative record shape

{
  "id": "<Event id>",
  "summary": "<Title>",
  "start": {},
  "end": {},
  "attendees": [],
  "status": "<confirmed, tentative or cancelled>"
}

See events operations

Calendars records

Calendars

Calendars a user owns or subscribes to.

Field	Type	Meaning / relationship
`id`	string	Calendar id
`summary`	string	Name
`timeZone`	string	Time zone
`accessRole`	string	owner, writer or reader

json · illustrative record shape

{
  "id": "<Calendar id>",
  "summary": "<Name>",
  "timeZone": "<Time zone>",
  "accessRole": "<owner, writer or reader>"
}

See calendars operations

Free and busy records

Free and busy

Availability across one or more calendars.

Field	Type	Meaning / relationship
`timeMin`	datetime	Window start
`timeMax`	datetime	Window end
`items`	array	Calendar ids to check
`calendars`	object	Busy blocks per calendar

json · illustrative record shape

{
  "timeMin": "<Window start>",
  "timeMax": "<Window end>",
  "items": [],
  "calendars": {}
}

See free and busy operations

Calendar ACL records

Calendar ACL

Who can see or edit a calendar.

Field	Type	Meaning / relationship
`id`	string	Rule id
`role`	string	none, freeBusyReader, reader, writer or owner
`scope`	object	Type and value of the grantee
`etag`	string	Version tag of the rule

json · illustrative record shape

{
  "id": "<Rule id>",
  "role": "<none, freeBusyReader, reader, writer or owner>",
  "scope": {},
  "etag": "<Version tag of the rule>"
}

See calendar acl operations

See the Google Calendar world in the catalog