Documentation
¶
Overview ¶
Package calendar provides calendar management tools for agents. It enables agents to create, read, update, and delete calendar events using the Google Calendar API, making scheduling accessible through natural language.
Problem: "Schedule a standup at 3pm tomorrow" is one of the most common agent requests, yet without this tool agents have no way to interact with calendars. This package bridges that gap, enabling meeting scheduling, availability checks, and event management through conversational AI.
Available tools (prefixed with google_calendar_ when registered):
- google_calendar_list_events — list upcoming events in a time range
- google_calendar_next_events — list upcoming events for a human-friendly duration
- google_calendar_create_event — schedule a new event with title, time, attendees
- google_calendar_update_event — modify an existing event
- google_calendar_delete_event — cancel an event
- google_calendar_free_busy — check availability for one or more calendars
- google_calendar_quick_add — create event from natural language text
- google_calendar_find_time — find a common free slot for attendees
Safety guards:
- 30-second API timeout
- Create/update/delete operations can be gated behind HITL approval
- Events limited to 100 per list query
Authentication:
- Embedded client (Option 1): Build with -X to inject GoogleClientID and GoogleClientSecret; then users can "just sign in" without providing credentials. See pkg/tools/google/oauth.
- OAuth2: Set CredentialsFile (path or JSON content of credentials.json) and one of: TokenFile (path to token.json), Token (inline token JSON), or Password (OAuth refresh token or inline token JSON).
- Service account: Set CredentialsFile to a service account key JSON (auto-detected by the "type" field).
Google Calendar API does not support username/password login; it requires OAuth2 or a service account.
Package calendar provides a DataSource connector that enumerates Google Calendar events for configured calendars. It uses the Calendar API to list events in a time window and returns one NormalizedItem per event for the sync pipeline to vectorize.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CalendarConnector ¶
type CalendarConnector struct {
// contains filtered or unexported fields
}
CalendarConnector implements datasource.DataSource for Google Calendar. It lists events for each calendar in scope.CalendarIDs over a forward window (e.g. 30 days) and returns one NormalizedItem per event.
func NewCalendarConnector ¶
func NewCalendarConnector(svc *gcal.Service) *CalendarConnector
NewCalendarConnector returns a DataSource that lists events from the given Google Calendar service. The caller must provide an initialised *gcal.Service (e.g. from the same OAuth or service-account setup as the calendar tools).
func (*CalendarConnector) ListItems ¶
func (c *CalendarConnector) ListItems(ctx context.Context, scope datasource.Scope) ([]datasource.NormalizedItem, error)
ListItems lists events for each calendar in scope.CalendarIDs from now through the next 30 days, and returns one NormalizedItem per event with ID "calendar:calendarID:eventID". Content is summary + description; metadata includes start time and location.
func (*CalendarConnector) Name ¶
func (c *CalendarConnector) Name() string
Name returns the source identifier for Calendar.
type ToolProvider ¶
type ToolProvider struct {
// contains filtered or unexported fields
}
ToolProvider wraps the calendar tools and satisfies the tools.ToolProviders interface so calendar tools can be passed directly to tools.NewRegistry. Each calendar instance is identified by a name (e.g. "work", "personal") which prefixes all tool names so the LLM can distinguish between multiple calendar integrations. Secrets are resolved at runtime (not construction time) so that rotated credentials are picked up automatically.
func NewToolProvider ¶
func NewToolProvider(secretProvider security.SecretProvider) *ToolProvider
NewToolProvider creates a ToolProvider for the calendar tools. The SecretProvider is stored but secrets are only resolved when each tool handler executes, supporting credential rotation.
Source Files