Give Your AI Agent a Managed Calendar

How does an agent account get a calendar?

An agent account's grant carries email and calendar on a single identity. When you create the account, the API provisions one grant — the same entity type used for Gmail or Outlook connections — and every calendar endpoint works against it immediately. There is no second OAuth handshake, no Google Cloud project, and no Microsoft Entra app registration. The agent that sends mail also books meetings.

This matters because scheduling is where most email agents stall. A support agent that can read a request but can't offer a time slot has to hand the conversation back to a human. Pairing email and calendar on one grant closes that loop. The agent account architecture groups all three capabilities — email, calendar, and contacts — under the workspace your account already owns.

How do I create an agent account with calendar access?

Calendar access ships with every agent account, so creation is a single command and the calendar is live the moment it returns. The nylas agent account create command provisions the grant in under 2 seconds and stores it locally as your active identity, so calendar commands resolve it automatically. The availability and event examples below also pass the grant explicitly as $NYLAS_GRANT_ID, which keeps them safe to drop into a script or cron job where no interactive config exists.

nylas agent account create scheduler@yourapp.nylas.email

✓ Agent account created successfully!

Email:      scheduler@yourapp.nylas.email
Provider:   nylas
Status:     valid

Confirm the grant is the active identity before scheduling. The nylas calendar list command returns the calendars attached to the resolved grant. A fresh agent account exposes one primary calendar, which is all most agents need:

nylas calendar list --json | jq '.[] | {id, name, is_primary}'

How does an agent check availability?

The nylas calendar availability check command answers one question: are these people free in this window? It takes a list of participant emails plus a start and end timestamp — say a 1 hour window — then returns the free or busy state for each in a single request. Use ISO 8601 timestamps in UTC so a cron job, a CI runner, and a laptop never disagree about timezone math.

nylas calendar availability check "$NYLAS_GRANT_ID" \
  --emails alice@example.com,bob@example.com \
  --start "2026-06-10T13:00:00Z" \
  --end "2026-06-10T14:00:00Z" \
  --json

An availability check is the deterministic guard an agent runs before it commits to a slot. The LLM proposes a time; the availability call confirms it. Wiring this check between the model's suggestion and the booking call is what keeps an agent from confidently double-booking a calendar it can't actually see.

How does an agent find a meeting time across timezones?

When the agent doesn't have a candidate slot yet, the nylas calendar find-time command searches for one. It takes participants and their IANA timezones, then returns slots that fit everyone's working hours. The defaults search 7 days ahead for a 1-hour meeting between 09:00 and 17:00, and exclude weekends — sensible starting points you can override per call.

nylas calendar find-time \
  --participants alice@example.com,bob@example.com \
  --timezones America/Toronto,Europe/London \
  --duration 45m \
  --days 7

The command prints a ranked list of up to 5 suggested times, each scored out of 100 on working-hours fit, time quality, and weekday — a picker for a human or an agent to choose from, not a JSON payload to parse. To turn a chosen slot into a confirmed booking, verify it with availability check and then create the event. Timezone math is the classic place a hand-rolled scheduler breaks. The --timezones list aligns position-by-position with --participants, so Toronto maps to Alice and London to Bob. The CLI intersects working windows across a 5-hour offset and only returns slots that are daytime for both people. Adjust the day with --working-start and --working-end when a team runs off the 09:00–17:00 default.

How does an agent book a meeting?

Once a slot is confirmed, the agent books it with nylas calendar events create. The command writes the event to the grant's primary calendar and adds each --participant as an attendee, which dispatches a standard calendar invite. The event is created on the agent's own calendar — the identity that owns the meeting is the agent, not a borrowed human account.

nylas calendar events create "$NYLAS_GRANT_ID" \
  --title "Onboarding call" \
  --start "2026-06-10T16:00:00Z" \
  --end "2026-06-10T16:45:00Z" \
  --participant alice@example.com \
  --participant bob@example.com \
  --location "Google Meet" \
  --description "Kickoff and account setup" \
  --json

The invite Nylas sends follows RFC 5545, the iCalendar standard every major calendar client renders, so Gmail, Outlook, and Apple Calendar all show the agent's meeting natively. Mark the event with --busy when the slot should block the agent's own free/busy lookups — a release window or a held hour that future find-time calls must route around.

How does an agent read its own schedule?

Agents need to read their calendar before they act on it — to summarize the day, detect a conflict, or decide whether to accept a new request. The nylas calendar events list command returns upcoming events as structured JSON. Pipe it through jq to hand the model a compact view instead of a full payload.

nylas calendar events list --days 1 --json \
  | jq '.[] | {title, start: .when.start_time, attendees: [.participants[].email]}'

Reducing the payload before it reaches the LLM is a cost lever, not just tidiness. A raw event object can run several hundred tokens; the projection above trims it to three fields. Across a daily standup summary over 20 events, that's the difference between roughly 6,000 tokens and 600 — a 10x reduction that compounds on every run. For a deeper pattern, see extracting structured data with jq.

Why use an agent-account calendar instead of Google or Graph APIs?

A provider calendar API gives an agent a real human's calendar; an agent-account calendar gives the agent its own. For an autonomous scheduler, the second model is usually what you want — the agent owns the meetings it books, and revoking the agent revokes one grant rather than a person's Google or Microsoft session. The setup cost is also different: a single command that returns in under 2 seconds versus an OAuth consent screen and a cloud-console app registration.

Both models speak the same Nylas v3 Calendar API, so you can mix them: an agent might read a customer's connected calendar for availability while booking on its own managed identity. When the agent needs a human's real calendar, connect it as a normal grant; when the agent needs a calendar of its own, the agent account already has one.

Next steps

• Getting Started with Agent Accounts — the 5-entity architecture and why one grant carries email, calendar, and contacts
• Build a Meeting-Booking Assistant Agent — the full read-request, find-time, book, confirm loop on one agent account
• Build a Recruiting Interview Coordinator — schedule across a candidate and a multi-person interview panel
• Give Your AI Agent a Contacts Directory — the third capability on the same grant: resolve names, group recipients, and dedupe
• Check Calendar Availability from the CLI — deeper coverage of free/busy, find-time, and multi-timezone scheduling
• Create Calendar Invites from the CLI — event creation, attendees, recurrence, and reminders in detail
• Stop Your AI Agent From Going Rogue — attach a containment policy so an agent can't email or invite arbitrary recipients
• Full command reference — every nylas calendar and nylas agent flag and subcommand
• Nylas v3 Calendar API documentation — the API surface behind these CLI commands