Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
Outlook Calendar (msCalendar)
| Field | Value |
|---|---|
| Category | microsoft (class group = ("microsoft", "tool")) |
| Backend handler | server/nodes/microsoft/calendar/__init__.py (CalendarNode, on ActionNode); Graph plumbing in _base.py (graph_request, mailbox_base, track_microsoft_usage); token refresh in _auth_helper.py |
| Tests | server/tests/nodes/test_microsoft.py |
| Skill (if any) | server/skills/productivity_agent/ms-calendar-skill/SKILL.md (allowed-tools: "ms_calendar") |
| Dual-purpose tool | yes - tool name ms_calendar |
Purpose
Create, list, update and delete Outlook Calendar events through Microsoft
Graph v1.0, for the signed-in user's calendar or a shared mailbox's
calendar. list reads calendarView over a date window that accepts
today / today+Nd shortcuts. Same auth and bookkeeping plumbing as
msMail: proactive token refresh, Connection facade, one
zero-cost usage row per operation.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Declared, but hideInputHandle is auto-set (usable_as_tool = True, class does not declare hide_input_handle) |
Parameters
extra="ignore" on the model.
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
operation |
create | list | update | delete |
list |
no | - | Operation dispatch key |
mailbox |
string | "" |
no | - (always shown) | Shared mailbox address; empty targets /me, else /users/{address} |
event_id |
string | "" |
yes* | update, delete |
Graph event id |
title |
string | "" |
yes* | operation=create |
Event subject |
body |
string | "" |
no | operation=create |
Text body |
start_time |
string | "" |
yes* | operation=create |
ISO 8601 local datetime |
end_time |
string | "" |
yes* | operation=create |
ISO 8601 local datetime |
location |
string | "" |
no | operation=create |
location.displayName |
attendees |
string | "" |
no | operation=create |
Comma- or semicolon-separated; all typed required |
timezone |
string | UTC |
no | operation=create |
timeZone for start / end. Also applied by update (see Decision Logic) |
start_date |
string | "" |
no | operation=list |
ISO datetime, today, or today+Nd; empty = today 00:00 UTC |
end_date |
string | "" |
no | operation=list |
ISO datetime, today, or today+Nd; empty = now + 7 days |
max_results |
int (1..250) | 10 |
no | operation=list |
$top |
update_title |
string | "" |
no | operation=update |
subject patch |
update_start_time |
string | "" |
no | operation=update |
start.dateTime patch |
update_end_time |
string | "" |
no | operation=update |
end.dateTime patch |
update_body |
string | "" |
no | operation=update |
Text body patch |
update_location |
string | "" |
no | operation=update |
location.displayName patch |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | CalendarOutput; hideOutputHandle auto-set |
output-tool |
- | Auto-appended for usable_as_tool |
Output payload (TypeScript shape)
The op returns a CalendarOutput instance; unset fields are omitted.
// create and update
{ operation: "create" | "update"; event_id: string; title: string; start: string; end: string;
location: string; web_link: string }
// list
{ operation: "list"; count: number; time_range: { start: string; end: string };
events: Array<{ event_id, title, start, end, location, organizer, web_link, is_all_day }> }
// delete
{ operation: "delete"; deleted: true; event_id: string }
Logic Flow
flowchart TD
A[Operation dispatch] --> B{params.operation}
B -- create --> C1[require title, start_time, end_time] --> C2[POST base/events subject, start/end with timezone, body?, location?, attendees?] --> U[track_microsoft_usage]
B -- list --> L1[_iso_or_shortcut start_date; end_date with 7 day default] --> L2[GET base/calendarView startDateTime endDateTime $top $orderby start/dateTime $select] --> U
B -- update --> P1[require event_id] --> P2[build patch from non-empty update_* fields]
P2 -- empty --> ERR[NodeUserError No update fields provided]
P2 -- ok --> P3[PATCH base/events/id] --> U
B -- delete --> D1[require event_id] --> D2[DELETE base/events/id -> 204] --> U
U --> OUT[Return CalendarOutput]
G[every graph_request: ensure_fresh_microsoft_token -> Connection microsoft -> status >= 400 raises NodeUserError]
Decision Logic
- Validation (
NodeUserError):createneedstitle,start_timeandend_time;updateanddeleteneedevent_id;updatewith no non-emptyupdate_*field; unknown operation; invalidmailbox. - Date shortcuts (
_iso_or_shortcut,datetime.utcnow()based, naive ISO output): empty ortodaywithdefault_offset_days == 0(start_date) -> today at 00:00:00; empty ortodaywith the 7-day default (end_date) -> now plus 7 days (NOT midnight);today+Nd-> now plus N days; anything else passes through verbatim. A malformedtoday+...value raisesValueErrorfromint(), which is not aNodeUserError. list:$top = min(max_results, 250),$orderby=start/dateTime,$select=id,subject,start,end,location,organizer,webLink,isAllDay; usage count = number returned;time_rangeechoes the resolved window.create:bodyis alwayscontentType: Text;attendeesentries are{"emailAddress": {"address"}, "type": "required"}.update: only supplied fields are patched.update_start_time/update_end_timereuse thetimezoneparam, whosedisplayOptionsshow it only forcreate- through the panel an update therefore always uses the defaultUTCunless the field was set while the operation wascreate; tool calls can pass it explicitly.event_idin the output falls back to the param when Graph's response lacksid.delete: Graph returns 204 ->graph_requestyieldsNone; output is{deleted: true, event_id}.- Auth: identical to
msMail-ensure_fresh_microsoft_tokenraises an annotatedPermissionError(provider="microsoft",reason="missing",auth="oauth2") when not connected; the first call per process refreshes; refresh failures fall back to the stored token. - Error paths: Graph status >= 400 ->
NodeUserError("Microsoft Graph error (<status>): <code>: <message>").
Side Effects
- Database writes: one
api_usage_metricsrow per op (service="microsoft_graph";create->event_create,list->event_list,update->event_update,delete->event_delete; cost 0.0). Token refresh persists tokens viaauth_service.store_oauth_tokens. - External API calls:
POST {base}/events,GET {base}/calendarView,PATCH {base}/events/{id},DELETE {base}/events/{id}onhttps://graph.microsoft.com/v1.0withAuthorization: Bearer. - Broadcasts: standard node status only.
- File I/O: none.
External Dependencies
- Credentials:
MicrosoftCredential(id = "microsoft", OAuth2, authority/organizations;Calendars.ReadWriteandCalendars.ReadWrite.Sharedamong the scopes inserver/config/microsoft_apis.json;microsoft_client_id/microsoft_client_secretapi-key rows). - Services: Microsoft Graph v1.0;
login.microsoftonline.comfor refresh. - Python packages:
httpx,pydantic;services.plugin.connection. - Environment variables: none read directly.
Edge cases & known limits
start_time/end_timeare sent verbatim; an unparseable value is rejected by Graph (surfaced asNodeUserError), not by the node.listusescalendarView, so recurring-event instances are expanded;is_all_dayrides along per instance.createsends attendees invitations as Graph normally does for a POST to/events(nosendNotificationscontrol is exposed).annotations = {"destructive": False, ...}althoughdeleteremoves events.- Shared calendars require Full Access on the mailbox plus the
.Sharedscope; the node cannot detect the missing grant ahead of Graph's 403.
Related
- Skills using this as a tool: ms-calendar-skill
- Siblings:
msMail,msMailReceive - Architecture docs: Plugin System, Pricing Service