Meetings and Google Calendar

The calendar lets the AI agent turn a conversation into a real meeting. It is configured in AI → Calendar and used by an agent through four tools: available slots, book, reschedule, and cancel.

Google Calendar is the provider available today. The runtime itself is written against a provider-neutral interface, so meeting types, bookings, and agent tools do not depend on Google specifics.

Connecting an account

Press Connect Google Calendar. The authorization window is opened with a one-time state that is bound to your bot and account and expires after five minutes, uses PKCE, and returns to one exact redirect address. Requested access is limited to the calendar list, calendar events, and free/busy information.

The refresh token is stored encrypted and is never shown again. The connection card shows only the account label and one of four states: Connected, Access expired, Disabled, or Failed. If access expires, connect the account again.

Disconnect calendar is blocked while an active agent still has calendar tools enabled — the dashboard names those agents. Remove the tools or pause the agent first.

Meeting types

A meeting type is what the agent actually offers. Each one holds:

  • Name shown to you in reports and to the customer in the event.
  • Calendar chosen from the connected account. The saved calendar identifier is stored encrypted and is not displayed again, so editing a meeting type asks you to pick the calendar once more.
  • Duration — from 5 to 480 minutes.
  • Time zone — an IANA name such as Europe/Berlin. It defines what the available hours below mean.
  • Available hours — from 1 to 28 weekly intervals given as HH:MM boundaries per weekday. Intervals must not overlap; an interval whose end is earlier than its start runs past midnight.
  • Minimum notice — 0 to 1 440 minutes before the start, below which booking is refused.
  • How far ahead bookings are allowed — 1 to 366 days.
  • Buffer before and Buffer after — 0 to 1 440 minutes each, kept free around the meeting.
  • Meeting type enabled — only enabled types can be offered or booked.

Show available slots previews the real result for the coming week, using the connected calendar rather than a simulation.

How a slot is chosen

Availability is computed from four inputs at once: the weekly hours of the meeting type, the busy intervals reported by the calendar, the buffers, and the bookings that already exist for that connection. Candidate starts are taken every 15 minutes; by default 10 slots are returned and never more than 20.

Times are shown in the customer's time zone and stored in UTC, so a daylight saving change shifts the offered local time rather than the stored moment.

Booking is deliberately careful:

  1. The chosen slot is validated again, immediately before anything is written.
  2. A pending booking is stored with an idempotency key, so a repeated request cannot create a second meeting.
  3. The event is created in the calendar, optionally with a video link.
  4. If the provider times out or answers with a retryable error, the booking is looked up by its idempotency key before anything is retried, so an ambiguous timeout does not produce a duplicate.
  5. Only then is the booking confirmed. The provider event identifier and the meeting link are stored encrypted.

Reschedule and cancel follow the same discipline, and a booking whose slot has become unavailable fails instead of overbooking.

Booking states are Pending, Confirmed, Rescheduled, Cancelled, and Failed.

Giving the tools to an agent

In the agent editor, under Allowed tools, enable the calendar actions you want:

  • Show available slots
  • Book a meeting
  • Reschedule a meeting
  • Cancel a meeting

Every enabled calendar tool must list at least one current, enabled meeting type; the launch check refuses to activate an agent otherwise. An active agent may use calendar tools only — no other tool is runnable in production yet.

The model never chooses a calendar, a customer, or a raw request. It may only propose a call whose arguments match the tool's closed schema, and the bot, the subscriber, and the allowed meeting types are taken from the server context. Tool calls have a 15-second deadline, are keyed by the turn and the position of the call, and are stored with meeting links and contact details redacted.

Reporting

AI → Analytics shows calendar actions and booking outcomes next to the other agent metrics, and AI → Calendar lists the bookings themselves.

Troubleshooting

  • Calendar tools are enabled, but there is no enabled meeting type — create one, or enable an existing one, before activating the agent.
  • The calendar list could not be loaded — the account may need to be reconnected; a connection identifier can be entered manually as a temporary fallback.
  • No free slots in the coming week — check the weekly hours, the minimum notice, the buffers, and whether the calendar is fully busy.
  • The meeting type is in use and cannot be deleted — it is referenced by an active agent's calendar tools.

Related pages