Imported from inference-gateway/google-calendar-agent (AGENTS.md). Install upstream with npx skills add inference-gateway/google-calendar-agent. Copyright stays with the author.

AGENTS.md

This file describes the agents available in this A2A (Agent-to-Agent) system.

Agent Overview

google-calendar-agent

Version: 0.5.9
Description: A Google Calendar A2A agent for AI assistants to interact with Google Calendar

This agent is built using the Agent Definition Language (ADL) and provides A2A communication capabilities.

Agent Capabilities

• Streaming: ✅ Real-time response streaming supported
• Push Notifications: ❌ Server-sent events not supported
• State History: ❌ State transition history not tracked

AI Configuration

System Prompt: You are a Google Calendar AI agent specialized in calendar management and scheduling operations.

Your primary capabilities:

1. Event Management: Create, update, delete, and retrieve calendar events
2. Scheduling Intelligence: Find available time slots and check for conflicts
3. Calendar Operations: List events with flexible time ranges and search queries

Key features:

• Support for both mock mode (demo/testing) and production Google Calendar API
• RFC3339 timestamp handling for accurate scheduling
• Intelligent conflict detection and availability checking
• Attendee management and location tracking
• Comprehensive event search and filtering

When helping users:

• Always validate time formats and ranges
• Provide clear feedback on scheduling conflicts
• Suggest alternative time slots when conflicts are detected
• Handle both simple and complex scheduling scenarios
• Maintain data accuracy and consistency with Google Calendar

Time and timezone handling:

• For any time-relative request ("today", "tomorrow", "next Friday", "in 2 hours"), call the get_current_datetime tool FIRST to anchor the current time and the user's IANA timezone. Do not guess.
• Emit RFC3339 timestamps with the offset of the user's timezone (e.g. 2026-05-20T14:00:00+02:00 for CEST), not UTC and not a provider-default like Pacific Time.
• If the user names an explicit timezone, prefer that over the configured default.

Your responses should be accurate, helpful, and focused on calendar management tasks.

Configuration:

Tools

This agent exposes 9 function-call tools:

Read (built-in)

• Description: Read a file from disk. Returns its contents, optionally sliced by line offset/limit. Use this to load SKILL.md bodies on demand.
• Parameters: file_path, offset, limit

list_calendar_events

• Description: List upcoming events from Google Calendar
• Tags: calendar, events, list, google
• Input Schema: Defined in agent configuration
• Output Schema: Defined in agent configuration

create_calendar_event

• Description: Create a new event in Google Calendar
• Tags: calendar, events, create, google
• Input Schema: Defined in agent configuration
• Output Schema: Defined in agent configuration

update_calendar_event

• Description: Update an existing event in Google Calendar
• Tags: calendar, events, update, google
• Input Schema: Defined in agent configuration
• Output Schema: Defined in agent configuration

delete_calendar_event

• Description: Delete an event from Google Calendar
• Tags: calendar, events, delete, google
• Input Schema: Defined in agent configuration
• Output Schema: Defined in agent configuration

get_calendar_event

• Description: Get details of a specific event from Google Calendar
• Tags: calendar, events, get, google
• Input Schema: Defined in agent configuration
• Output Schema: Defined in agent configuration

find_available_time

• Description: Find available time slots in the calendar
• Tags: calendar, availability, scheduling, google
• Input Schema: Defined in agent configuration
• Output Schema: Defined in agent configuration

check_conflicts

• Description: Check for scheduling conflicts in the specified time range
• Tags: calendar, conflicts, scheduling, google
• Input Schema: Defined in agent configuration
• Output Schema: Defined in agent configuration

get_current_datetime

• Description: Return the current date/time and the user's IANA timezone. Call this FIRST for any time-relative request (today, tomorrow, next Friday) before emitting RFC3339 timestamps to other calendar tools, so events land in the user's local timezone instead of an LLM-assumed default.
• Tags: time, timezone, context
• Input Schema: Defined in agent configuration
• Output Schema: Defined in agent configuration

Skills

This agent ships 1 markdown skill that are loaded into the system prompt at startup:

schedule-meeting

• Description: Use this when the user asks to schedule a meeting, book a slot, or find a time that works. Resolves a conflict-free booking by finding open slots, validating no overlap, and creating the event.
• Tags: calendar, scheduling, meeting
• Source: scaffolded locally (.agents/skills/schedule-meeting/SKILL.md)

Server Configuration

Port: 8080 Debug Mode: ❌ Disabled Authentication: ❌ Not required

API Endpoints

The agent exposes the following HTTP endpoints:

• GET /.well-known/agent-card.json - Agent metadata and capabilities
• GET /health - Health check endpoint
• POST /a2a - JSON-RPC endpoint for all A2A operations (skill execution, streaming, etc.)

Environment Setup

Required Environment Variables

Key environment variables you'll need to configure:

• PORT - Server port (configured: 8080)

Development Environment

• Flox Environment: ✅ Configured for reproducible development setup (flox activate)

Usage

Starting the Agent

# Install dependencies
go mod download

# Run the agent (the binary is a CLI; `start` boots the server)
go run . start

# Or use Task
task run

Communicating with the Agent

The agent implements the A2A protocol and can be communicated with via HTTP requests:

# Get agent information
curl http://localhost:8080/.well-known/agent-card.json

Refer to the main README.md for specific skill execution examples and input schemas.

Deployment

Deployment Type: Manual

• Build and run the agent binary directly
• Use provided Dockerfile for containerized deployment

Docker Deployment

# Build image
docker build -t google-calendar-agent .

# Run container
docker run -p 8080:8080 google-calendar-agent

Development

Project Structure

.
├── main.go                       # Server entry point
├── tools/                        # Function-call tools
│   └── read.go                   # Read a file from disk. Returns its contents, optionally sliced by line offset/limit. Use this to load SKILL.md bodies on demand.
│   └── list_calendar_events.go   # List upcoming events from Google Calendar
│   └── create_calendar_event.go  # Create a new event in Google Calendar
│   └── update_calendar_event.go  # Update an existing event in Google Calendar
│   └── delete_calendar_event.go  # Delete an event from Google Calendar
│   └── get_calendar_event.go     # Get details of a specific event from Google Calendar
│   └── find_available_time.go    # Find available time slots in the calendar
│   └── check_conflicts.go        # Check for scheduling conflicts in the specified time range
│   └── get_current_datetime.go   # Return the current date/time and the user's IANA timezone. Call this FIRST for any time-relative request (today, tomorrow, next Friday) before emitting RFC3339 timestamps to other calendar tools, so events land in the user's local timezone instead of an LLM-assumed default.
├── .agents/skills/               # Skill directories (SKILL.md + optional assets)
│   └── schedule-meeting/         # Use this when the user asks to schedule a meeting, book a slot, or find a time that works. Resolves a conflict-free booking by finding open slots, validating no overlap, and creating the event.
│       └── SKILL.md              # Playbook prepended to the system prompt
├── .well-known/                  # Agent configuration
│   └── agent-card.json           # Agent metadata
├── go.mod                        # Go module definition
└── README.md                     # Project documentation

Testing

# Run tests
task test
go test ./...

# Run with coverage
task test:coverage

Contributing

1. Implement business logic in skill files (replace TODO placeholders)
2. Add comprehensive tests for new functionality
3. Follow the established code patterns and conventions
4. Ensure proper error handling throughout
5. Update documentation as needed

Agent Metadata

This agent was generated using ADL CLI v0.5.9 with the following configuration:

• Language: Go
• Template: Minimal A2A Agent
• ADL Version: adl.inference-gateway.com/v1

For more information about A2A agents and the ADL specification, visit the ADL CLI documentation.