AI Tools

The optional Shiny.Calendar.Extensions.AI package exposes ICalendarStore as Microsoft.Extensions.AI tool functions (AIFunctions) for LLM agents. You opt-in per operation — read, create, update, delete — and optionally per calendar, an allow-list you control on behalf of the agent (this is not an OS permission prompt; the platform calendar permission must already be granted). AOT-compatible: hand-built schemas and JsonNode results, no reflection.

Setup

using Shiny.Calendar;
using Shiny.Calendar.Extensions.AI;

builder.Services.AddCalendarStore();                       // registers ICalendarStore
builder.Services.AddCalendarAITools(tools => tools
    .AddCalendar(CalendarAICapabilities.Read | CalendarAICapabilities.Create)
);

Resolve the bundle and hand the tools to any IChatClient:

var tools = sp.GetRequiredService<CalendarAITools>().Tools;
var response = await chatClient.GetResponseAsync(
    messages,
    new ChatOptions { Tools = [.. tools] }
);

Capabilities

CalendarAICapabilities is a [Flags] enum, so each operation toggles independently:

Flag	Tools exposed
Read	list_calendars, search_events, get_event
Create	create_event
Update	update_event
Delete	delete_event
Write	Create | Update | Delete
All	Read | Write

// read + create only — the agent can add events but not modify or delete them
.AddCalendar(CalendarAICapabilities.Read | CalendarAICapabilities.Create)

// full access
.AddCalendar(CalendarAICapabilities.All)

Scoping to specific calendars

AddCalendar(capabilities) applies to every calendar on the device. AddCalendar(calendarId, capabilities) applies to one calendar and replaces the global set for it — so a per-calendar entry can widen or narrow access. That covers the three shapes you normally want:

// 1. global — every calendar, same rules
builder.Services.AddCalendarAITools(tools => tools
    .AddCalendar(CalendarAICapabilities.Read)
);

// 2. mixed — read everything, but full read/write on the work calendar, and hide the private one
builder.Services.AddCalendarAITools(tools => tools
    .AddCalendar(CalendarAICapabilities.Read)
    .AddCalendar(workCalendarId, CalendarAICapabilities.All)
    .AddCalendar(privateCalendarId, CalendarAICapabilities.None)
);

// 3. strict allow-list — no global grant, so ONLY these calendars exist to the agent
builder.Services.AddCalendarAITools(tools => tools
    .AddCalendar(workCalendarId, CalendarAICapabilities.All)
    .AddCalendars([teamCalendarId, holidayCalendarId], CalendarAICapabilities.Read)
);

The tools enforce this on every call — the model cannot talk its way around the filter:

• list_calendars returns only calendars with at least one capability, each with an allowedOperations array (read / create / update / delete) so the model knows where it may write.
• search_events searches only readable calendars; passing a calendarId outside the filter is an error.
• get_event, update_event, and delete_event resolve the event’s calendar first and refuse when it isn’t allowed.
• create_event refuses a disallowed calendarId. When Create isn’t granted globally, omitting calendarId is an error too — the device default calendar can’t be vetted up front, so the model is told to pick a calendar from list_calendars.

A tool is generated when any calendar grants that capability, so AddCalendar(workId, All) on its own still produces create_event / update_event / delete_event — scoped to that calendar.

Filters chosen at runtime

Calendar ids are platform-assigned, so the ids you want are usually picked by the user and persisted. Use the service-provider overload — the callback runs when CalendarAITools is first resolved, so it can read your own services:

builder.Services.AddCalendarAITools((sp, tools) =>
{
    var settings = sp.GetRequiredService<AppSettings>();   // the ids the user picked
    tools.AddCalendars(settings.AgentCalendarIds, CalendarAICapabilities.All);
});

Generated Tools

Tool	Capability	Description
list_calendars	Read	Lists the allowed calendars (id, name, colour, read-only, allowedOperations).
search_events	Read	Events in a date window across the readable calendars, optional calendar id + free-text query.
get_event	Read	Full detail for one event (attendees, reminders, recurrence).
create_event	Create	Creates an event (title, start, end required; ISO-8601 dates).
update_event	Update	Updates supplied fields on an existing event.
delete_event	Delete	Deletes an event by id. Optional deleteSeries (default false) chooses one occurrence vs. this and all future ones.

Key Types

• AddCalendarAITools(Action<ICalendarAIToolBuilder>) — DI extension; throws if nothing is added.
• AddCalendarAITools(Action<IServiceProvider, ICalendarAIToolBuilder>) — same, but the callback runs on first resolve so the filter can come from your own services.
• ICalendarAIToolBuilder — AddCalendar(CalendarAICapabilities) (global), AddCalendar(string calendarId, CalendarAICapabilities), AddCalendars(IEnumerable<string> calendarIds, CalendarAICapabilities).
• CalendarAICapabilities [Flags] — None, Read, Create, Update, Delete, Write, All.
• CalendarAITools — resolve from DI; .Tools is IReadOnlyList<AITool>.

Caution

The AI tools assume permissions are already granted — they do not trigger the platform permission UI (which needs a foreground activity). Call ICalendarStore.RequestAccess(...) from the app before invoking the agent. delete_event is irreversible — instruct the model to confirm with the user first, and on a recurring event to ask whether they mean the single occurrence or the whole series before setting deleteSeries.

Combine with your app’s own functions

The functions your app exposes to Siri and Gemini can join these tools in the same chat. Shiny.AppFunctions.Extensions.AI turns them into AIFunctions with the same *AITools bundle shape, so you concatenate the .Tools lists into one ChatOptions.Tools.