Calendar API for AI Agents: Build a Google and Microsoft Availability Adapter

Build the provider-neutral calendar adapter in eight steps

Start with one meeting fixture: an organizer, three required people, one optional observer, Google and Microsoft accounts, and one participant with no connected calendar. The adapter should make provider differences explicit without making the model responsible for them.

1. 1

   Create a typed meeting-intent envelope

   Accept an organizer, duration, date window, booking deadline, meeting time zone, required and optional participants, working-hour rules, preferences, exclusions, approval mode, and permitted outreach channels. Give the request a stable ID and revision. The provider adapter should receive a bounded availability query, not an unstructured paragraph.
   • Reject a missing duration, date window, organizer, or required participant.
   • Use IANA time-zone names in the domain model.
   • Keep participant role separate from calendar account and provider.
2. 2

   Map consent to the smallest provider permission

   Google’s free/busy endpoint accepts dedicated free/busy scopes. Microsoft Graph lists Calendars.ReadBasic as the least-privileged permission for getSchedule. Store which user granted access, which source account is authoritative, which scopes apply, and whether access is active, expired, denied, or revoked. Do not request event-detail access when busy intervals satisfy the job.
   • Separate availability permission from event-write permission.
   • Show the user which account and action they are authorizing.
   • Never treat expired or denied access as an empty calendar.
3. 3

   Wrap Google free/busy behind one provider method

   Call Google Calendar’s free/busy query with RFC 3339 timeMin and timeMax, a response time zone, and bounded calendar IDs. Convert each returned busy range into your canonical interval. Preserve calendar-level errors such as not found or internal error beside the participant instead of dropping the whole response or pretending the calendar is open.
   • Respect Google’s documented calendar and group expansion limits.
   • Treat interval start as inclusive and end as exclusive.
   • Record retrieval time and provider request correlation for support.
4. 4

   Wrap Microsoft getSchedule without copying subjects

   Call Microsoft Graph getSchedule with SMTP addresses, a bounded time range, and an explicit response zone. Graph can return an availability view, schedule items, and working hours. The slot engine should consume status and interval evidence, not meeting subjects or locations. Convert Microsoft time-zone identifiers at the adapter boundary and keep the original identifier for audit.
   • Handle tentative, busy, out-of-office, and working-elsewhere policy explicitly.
   • Keep the documented result-size error distinct from ordinary no-availability.
   • Do not expose private schedule-item detail to the language model.
5. 5

   Normalize both providers into one availability contract

   Return participant_id, account_id, provider, window, busy_intervals, working_hours, retrieved_at, fresh_until, and errors. An empty busy array with no errors means something different from an empty array after a partial failure. Make that distinction impossible to lose.
   • Merge multiple authorized calendars for one participant before declaring them free.
   • Keep evidence versioned so a slot proposal can be marked stale.
   • Never infer a participant’s time zone from a numeric offset alone.
6. 6

   Add optional-sync fallback above the adapter

   One external participant may not authorize any calendar. Create an outreach task that asks for availability in plain language and records channel consent, message ID, time zone, response window, normalized intervals, and freshness. Feed that response into the same slot engine as provider data. The adapter should report not_connected; the coordination layer decides whether and how to ask.
   • Do not force an account or calendar connection to join the meeting.
   • Ask a narrow follow-up for ambiguous dates or zones.
   • Escalate required-participant silence rather than silently excluding the person.
7. 7

   Commit with provider-specific safety behind one booking command

   Re-check fresh availability before writing. Google’s event insert endpoint can send updates to guests and accepts required and optional attendees. Microsoft Graph’s create-event example includes a transactionId to reduce unnecessary retries and sends invitations to attendees. Your domain needs a separate idempotency key tied to meeting request, revision, and approved slot, plus stored provider event IDs.
   • One booking revision creates at most one canonical event.
   • An uncertain timeout triggers reconciliation before another insert.
   • Verify organizer, attendees, start, end, zone, and invitation behavior after the write.
8. 8

   Instrument evidence freshness, retries, and completion

   Trace availability calls, consent decisions, fallback messages, slot proposals, approvals, commits, and provider reconciliation by meeting request ID. Use separate retry policy for throttling, expired credentials, ambiguous participant replies, and uncertain writes. Finish only at confirmed, needs_review, or a terminal failure with a reason and safe next action.
   • Alert when a meeting remains in one state beyond its expected window.
   • Keep private event details out of logs and traces.
   • Expose source, freshness, and rejection reasons for the chosen slot.

Choose the calendar layer your agent actually needs

A provider adapter, a unified calendar API, and a scheduling execution layer remove different amounts of engineering work. Compare the complete meeting outcome.