ADK Java + Calendar, in depth: free/busy search, confirmed bookings, idempotent event IDs and least-privilege scopes for a scheduling agent

Three tools, three risk levels

Scheduling is three different jobs with three different risk levels, so give the model three tools. findFreeSlots reads availability for a list of people over a window and returns candidate slots. It cannot change anything. proposeMeeting takes a chosen slot, attendees and a title, validates and normalises them, and stores a proposal in session state, returning a proposal ID and a human-readable summary. It does not call the write API. bookProposal takes only a proposal ID, asks the user to confirm, and creates the event exactly once.

The split does two things. The user approves a concrete, fully resolved meeting, with absolute times in their own zone and the exact guest list, rather than a vague intention. And the model cannot alter the meeting between approval and booking, because the booking tool accepts nothing but the ID. The same shape works for email and payments; ADK Java email tools applies it to outbound mail.

Time zones belong in code, not in the model

Never let the model do time arithmetic. Models are good at understanding "Tuesday afternoon" and bad at knowing that the second Tuesday after a clock change is a different UTC offset. Make the model pass a local date, a local time and an IANA zone name, and let java.time do the rest. Two DST edge cases need explicit handling: a local time that does not exist (the spring-forward gap) and one that happens twice (the autumn overlap). ZonedDateTime.of silently shifts a gap time forward and silently picks the earlier offset in an overlap, which is exactly the silent behaviour you do not want in a booking, so check for both and return an error the model can relay.

import java.time.*;
import java.time.zone.ZoneRules;

static ZonedDateTime resolveLocal(String date, String time, String zone) {
    ZoneId zid = ZoneId.of(zone);                       // throws on unknown zone names
    LocalDateTime ldt = LocalDateTime.of(LocalDate.parse(date), LocalTime.parse(time));
    ZoneRules rules = zid.getRules();
    var offsets = rules.getValidOffsets(ldt);
    if (offsets.isEmpty())  throw new IllegalArgumentException(ldt + " does not exist in " + zone + " (DST gap)");
    if (offsets.size() > 1) throw new IllegalArgumentException(ldt + " is ambiguous in " + zone + " (DST overlap)");
    return ZonedDateTime.of(ldt, zid);
}

Store the user's zone in session state once, from their profile or by asking, and put it in the agent instruction so the model never guesses. Return times to the model already formatted in the user's zone with the offset visible, for example Tue 3 Nov 2026 15:00 (Europe/Berlin, UTC+01:00), so the confirmation the user reads is unambiguous.

Finding free slots

Availability comes from freebusy.query. It takes a window as RFC 3339 timestamps, an optional response time zone that defaults to UTC, and a list of calendars or groups. The reference caps group expansion at 100 members and calendar expansion at 50. Each calendar in the response carries a busy list of time ranges and, possibly, an errors list with reasons such as notFound, groupTooBig or tooManyCalendarsRequested. The critical rule: a calendar with an error is unknown, not free. Treating an empty busy list from a failed lookup as availability is how agents book over other meetings.

import com.google.api.client.util.DateTime;
import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.*;
import java.time.*;
import java.util.*;

public List<Interval> busyFor(Calendar api, List<String> emails, Instant from, Instant to) throws java.io.IOException {
    FreeBusyRequest req = new FreeBusyRequest()
        .setTimeMin(new DateTime(from.toEpochMilli()))
        .setTimeMax(new DateTime(to.toEpochMilli()))
        .setTimeZone("UTC")
        .setItems(emails.stream().map(e -> new FreeBusyRequestItem().setId(e)).toList());
    FreeBusyResponse resp = api.freebusy().query(req).execute();

    List<Interval> busy = new ArrayList<>();
    for (String email : emails) {
        FreeBusyCalendar cal = resp.getCalendars().get(email);
        if (cal == null || (cal.getErrors() != null && !cal.getErrors().isEmpty())) {
            throw new UnknownAvailability(email);           // unknown is not free
        }
        for (TimePeriod t : cal.getBusy()) {
            busy.add(new Interval(Instant.ofEpochMilli(t.getStart().getValue()),
                                  Instant.ofEpochMilli(t.getEnd().getValue())));
        }
    }
    return Interval.merge(busy);                            // sort by start, coalesce overlaps
}

Slot generation is then plain code: walk the window in steps (15 minutes works well), keep candidates that sit inside every attendee's working hours in their own zone, do not overlap the merged busy list, and leave a buffer before and after. Return at most five slots, ranked by how early they are and how few people are near the edge of their day. A short list keeps the model's reply readable and its context small. If an attendee's availability is unknown, say so in the result, for example {"unknown": ["ana@partner.com"]}, so the model can tell the user rather than pretend.

Booking exactly once

Booking needs two guarantees: the user approved this exact meeting, and a retry cannot create a second one. ADK's advanced confirmation flow handles the first. The tool calls toolContext.requestConfirmation(hint, payload) and returns a pending status; the client renders the hint and answers with an adk_request_confirmation function response; ADK re-invokes the tool, which reads toolContext.toolConfirmation().

The Calendar API handles the second, if you let it. Clients may choose an event's ID, as long as it uses base32hex characters (lowercase a to v and digits), is 5 to 1,024 characters long and is unique within the calendar. Lowercase hexadecimal is a subset of base32hex, so a SHA-256 of the user and proposal IDs is a valid, deterministic event ID. A retry after a timeout reuses the same ID. Google's reference does not document the response to a duplicate ID, and notes that collision detection at creation time is not guaranteed; in practice a duplicate insert is rejected with a 409 Conflict, so treat a 409 as "possibly already booked" and confirm with events().get rather than assuming either outcome.

@Schema(description = "Book a meeting previously created by proposeMeeting. Requires user approval. "
                    + "Pass only the proposalId.")
public Map<String, Object> bookProposal(
        @Schema(name = "proposalId", description = "Id returned by proposeMeeting") String proposalId,
        ToolContext toolContext) {
    @SuppressWarnings("unchecked")
    Map<String, Object> prop = (Map<String, Object>) toolContext.state().get("proposal:" + proposalId);
    if (prop == null) return error("NO_PROPOSAL", "No proposal " + proposalId + " in this session.");

    Optional<ToolConfirmation> confirmation = toolContext.toolConfirmation();
    if (confirmation.isEmpty()) {
        toolContext.requestConfirmation("Book \"" + prop.get("title") + "\" " + prop.get("whenDisplay")
                + " with " + prop.get("attendees") + "? Invitations will be sent.", Map.of("proposalId", proposalId));
        return Map.of("status", "pending", "message", "Waiting for the user to approve the booking.");
    }
    if (!confirmation.get().confirmed()) {
        return Map.of("status", "cancelled", "message", "The user declined this booking.");
    }
    String eventId = gateway.eventIdFor(toolContext.userId(), proposalId);   // sha256 hex, 64 chars
    BookingOutcome out = gateway.insertOnce(toolContext.userId(), eventId, prop);
    return Map.of("status", out.status(), "eventId", eventId, "link", out.htmlLink().orElse(""));
}

// Inside CalendarGateway: the only code that writes to the API
Event ev = new Event()
    .setId(eventId)
    .setSummary(title)
    .setStart(new EventDateTime().setDateTime(new DateTime(start.toInstant().toEpochMilli()))
                                 .setTimeZone(start.getZone().getId()))
    .setEnd(new EventDateTime().setDateTime(new DateTime(end.toInstant().toEpochMilli()))
                               .setTimeZone(end.getZone().getId()))
    .setAttendees(attendees.stream().map(a -> new EventAttendee().setEmail(a)).toList());
try {
    Event created = api.events().insert("primary", ev).setSendUpdates("all").execute();
    return BookingOutcome.created(created.getHtmlLink());
} catch (GoogleJsonResponseException e) {
    if (e.getStatusCode() == 409) {                       // observed for duplicate ids; verify, don't assume
        Event existing = api.events().get("primary", eventId).execute();
        return BookingOutcome.alreadyExists(existing.getHtmlLink());
    }
    throw e;
}

The sendUpdates parameter accepts all, externalOnly or none. Choose it in the gateway from policy, never from a model argument, and show the consequence in the confirmation hint. Register the tools with FunctionTool.create(calendarTools, "bookProposal") and its siblings, as described in writing a FunctionTool. One documented limit to check for your ADK version: confirmation was not supported with DatabaseSessionService or VertexAiSessionService when this was written, and a client that never renders the request leaves the call pending forever.

Scopes and credentials

Calendar's OAuth scopes are fine-grained enough to give each tool only what it needs. Request the narrowest set, and request write scopes incrementally, the first time a user actually books.

All scopes are prefixed https://www.googleapis.com/auth/. Tokens belong in the gateway, keyed by toolContext.userId(), never in session state or the prompt, so a transcript leak does not leak credentials. Enforce authorisation at the gateway too: the model can only book on behalf of the authenticated user, whatever the conversation claims. Authorisation at the agent boundary covers that pattern in general.

Reading events without obeying them

If the agent can also list or read events, everything in a title, description or location was written by someone else, possibly an outsider who sent an invitation. Return only the fields the task needs (start, end, title truncated to 100 characters, organiser, response status), strip descriptions by default, and wrap the result in a field the instruction names as untrusted data. Then make the structural defence carry the weight: reading tools cannot write, every write needs user confirmation, and the gateway rejects attendee domains outside policy. A prompt injection that reaches the model can then at most produce a proposal the user declines.

Worked example: one meeting across a clock change

On Friday 30 October 2026, a user in Berlin writes: "Find 30 minutes with Ana from the partner team next week, afternoons." The agent calls findFreeSlots with both addresses, a window of Monday to Friday and the zone Europe/Berlin. Ana's calendar returns notFound because the partner domain does not share free/busy data, so the tool returns three slots based on the user's calendar alone plus unknown: [ana@partner.com]. The model says so and offers the slots anyway. The user picks Tuesday at 15:00. proposeMeeting resolves it to 2026-11-03T15:00+01:00; the clocks went back on 25 October, so the offset is UTC+1, not the UTC+2 the model might have carried over from the week before the change. The confirmation reads "Book 'Partner sync' Tue 3 Nov 2026 15:00 (UTC+01:00) with ana@partner.com? Invitations will be sent." The user approves; the insert times out after the server committed it; the retry reuses the hashed ID, gets a conflict, fetches the existing event and returns its link. Ana receives one invitation.

Failure modes

• Meeting an hour off: the model computed an offset. Move all conversion into java.time and reject DST gaps and overlaps.
• Double booking over a busy slot: a free/busy error was read as free. Treat any calendar error as unknown.
• Duplicate invitations: a retry generated a new event ID. Derive the ID from the proposal.
• Booking stuck pending: the client never answered the confirmation, or the session store does not support it. Test the full round trip in your UI.
• 403 on insert: the write scope was never granted. Request it incrementally and surface a re-consent link.
• Quota errors under load: retry with exponential backoff and jitter, and cache free/busy results for a minute per window. Tool error wrapping shows how to return these to the model as structured errors.
• Agent obeys text in an invitation: event content reached the model as instructions. Truncate, label as untrusted and rely on confirmation.

Trade-offs

Per-user OAuth keeps every action attributable and is the right default for consumer and most workplace agents; the cost is consent flows and token refresh handling. In Google Workspace an administrator can instead grant a service account domain-wide delegation so it can act as users, which removes the consent friction but turns one credential into access to every calendar in the domain; if you choose it, restrict the delegated scopes to the freebusy and owned-events scopes above. Server-side proposals cost a little session state and an extra turn, and in return make every write reviewable. Asking for confirmation on every booking adds friction for internal one-to-ones; a policy that auto-approves meetings with no external guests inside working hours is reasonable, as long as the gateway, not the model, decides which bookings qualify.

What to do next

1. Split your calendar capability into read, propose and book tools; only the booking tool writes.
2. Store each user's IANA zone and resolve every time with java.time, rejecting DST gaps and overlaps.
3. Treat any free/busy error as unknown availability and report it to the user.
4. Derive event IDs from a hash of user and proposal, and handle a conflict by fetching the existing event.
5. Use ADK's advanced confirmation with a hint that shows absolute time, zone and guests.
6. Request calendar.freebusy first and the owned-events write scope only at first booking.
7. Keep tokens and notification policy in a gateway the model never sees.
8. Test a DST week, a timed-out insert and an injected event description before launch.