Timezone and Date Handling for Global AI Agents

Why Timezone Handling Is Harder Than You Think

When an AI agent tells a user "your appointment is at 3 PM," the natural follow-up question is: 3 PM where? Global agents must resolve ambiguous time references, convert between zones, and present dates in the format the user expects. Getting this wrong causes missed meetings, incorrect data analysis, and eroded trust.

The core complexity comes from three sources: timezone offset is not fixed (daylight saving time changes it), date format conventions vary by locale (MM/DD vs DD/MM), and natural language time references ("next Tuesday," "tomorrow morning") depend on the user's local time, not the server's.

Timezone-Aware Agent State

Store all timestamps in UTC internally and convert only at the presentation layer. Attach the user's timezone to their session context.

flowchart LR
    INPUT(["User intent"])
    PARSE["Parse plus<br/>classify"]
    PLAN["Plan and tool<br/>selection"]
    AGENT["Agent loop<br/>LLM plus tools"]
    GUARD{"Guardrails<br/>and policy"}
    EXEC["Execute and<br/>verify result"]
    OBS[("Trace and metrics")]
    OUT(["Outcome plus<br/>next action"])
    INPUT --> PARSE --> PLAN --> AGENT --> GUARD
    GUARD -->|Pass| EXEC --> OUT
    GUARD -->|Fail| AGENT
    AGENT --> OBS
    style AGENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style OBS fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff

from dataclasses import dataclass
from datetime import datetime, timezone
from zoneinfo import ZoneInfo
from typing import Optional

@dataclass
class UserTimezoneContext:
    timezone_name: str  # e.g., "America/New_York"
    locale: str = "en-US"

    @property
    def tz(self) -> ZoneInfo:
        return ZoneInfo(self.timezone_name)

    def now(self) -> datetime:
        """Current time in the user's timezone."""
        return datetime.now(timezone.utc).astimezone(self.tz)

    def to_user_time(self, utc_dt: datetime) -> datetime:
        """Convert a UTC datetime to the user's local time."""
        if utc_dt.tzinfo is None:
            utc_dt = utc_dt.replace(tzinfo=timezone.utc)
        return utc_dt.astimezone(self.tz)

    def to_utc(self, local_dt: datetime) -> datetime:
        """Convert a user's local datetime to UTC."""
        if local_dt.tzinfo is None:
            local_dt = local_dt.replace(tzinfo=self.tz)
        return local_dt.astimezone(timezone.utc)

Detecting the User's Timezone

Timezone detection typically relies on client-side JavaScript sending the Intl timezone, or IP-based geolocation as a fallback.

import httpx
from typing import Optional

class TimezoneDetector:
    async def from_ip(self, ip_address: str) -> Optional[str]:
        """Detect timezone from IP using a geolocation API."""
        try:
            async with httpx.AsyncClient() as client:
                resp = await client.get(
                    f"http://ip-api.com/json/{ip_address}",
                    params={"fields": "timezone,status"},
                )
                data = resp.json()
                if data.get("status") == "success":
                    return data.get("timezone")
        except Exception:
            pass
        return None

    def from_utc_offset(self, offset_minutes: int) -> str:
        """Map a UTC offset to a common timezone (imprecise but useful as fallback)."""
        offset_map = {
            -480: "America/Los_Angeles",
            -420: "America/Denver",
            -360: "America/Chicago",
            -300: "America/New_York",
            0: "Europe/London",
            60: "Europe/Paris",
            330: "Asia/Kolkata",
            540: "Asia/Tokyo",
            600: "Australia/Sydney",
        }
        return offset_map.get(offset_minutes, "UTC")

Locale-Aware Date Formatting

Different locales expect different date formats. Build a formatter that respects the user's conventions.

from babel.dates import format_datetime, format_date, format_time
from datetime import datetime

class LocaleDateFormatter:
    def __init__(self, locale: str = "en_US", tz_name: str = "UTC"):
        self.locale = locale
        self.tz_name = tz_name

    def format_full(self, dt: datetime) -> str:
        """Format datetime with full locale conventions."""
        return format_datetime(dt, format="long", locale=self.locale, tzinfo=ZoneInfo(self.tz_name))

    def format_short_date(self, dt: datetime) -> str:
        return format_date(dt, format="short", locale=self.locale)

    def format_time_only(self, dt: datetime) -> str:
        return format_time(dt, format="short", locale=self.locale, tzinfo=ZoneInfo(self.tz_name))

    def format_relative(self, dt: datetime, now: datetime) -> str:
        """Human-readable relative time like 'in 2 hours' or '3 days ago'."""
        diff = dt - now
        seconds = diff.total_seconds()
        if abs(seconds) < 60:
            return "just now"
        minutes = int(seconds / 60)
        if abs(minutes) < 60:
            return f"in {minutes} minutes" if minutes > 0 else f"{abs(minutes)} minutes ago"
        hours = int(minutes / 60)
        if abs(hours) < 24:
            return f"in {hours} hours" if hours > 0 else f"{abs(hours)} hours ago"
        days = int(hours / 24)
        return f"in {days} days" if days > 0 else f"{abs(days)} days ago"

Cross-Timezone Scheduling

When an agent schedules a meeting between users in different timezones, present the time in each participant's local zone.

from dataclasses import dataclass
from typing import List

@dataclass
class Participant:
    name: str
    timezone: str

def format_meeting_for_participants(
    utc_time: datetime, participants: List[Participant], formatter_locale: str = "en_US"
) -> dict:
    """Show meeting time in each participant's local timezone."""
    result = {"utc": utc_time.isoformat(), "local_times": []}
    for p in participants:
        tz = ZoneInfo(p.timezone)
        local = utc_time.astimezone(tz)
        fmt = LocaleDateFormatter(locale=formatter_locale, tz_name=p.timezone)
        result["local_times"].append({
            "participant": p.name,
            "timezone": p.timezone,
            "local_time": fmt.format_full(local),
        })
    return result

# Usage
meeting_utc = datetime(2026, 3, 20, 14, 0, tzinfo=timezone.utc)
participants = [
    Participant("Alice", "America/New_York"),
    Participant("Kenji", "Asia/Tokyo"),
    Participant("Priya", "Asia/Kolkata"),
]
schedule = format_meeting_for_participants(meeting_utc, participants)

FAQ

Should I store the user's timezone in the database or detect it every time?

Store it. Timezone detection from IP is imprecise and adds latency. Let users set their timezone explicitly during onboarding, detect it via JavaScript as a default, and allow them to change it in settings. Store the IANA timezone name (like "America/Chicago"), not a raw UTC offset.

How do I handle "tomorrow" or "next Monday" in user messages?

Parse relative date references using the user's local time, not the server's UTC clock. Libraries like dateparser or python-dateutil can parse natural language dates. Always confirm with the user by echoing back the resolved date in their local format before scheduling anything.

What about daylight saving time transitions?

Always use IANA timezone names (ZoneInfo) rather than fixed offsets. The zoneinfo module in Python 3.9+ handles DST transitions automatically. Never store or compute with raw offset values like UTC-5, because that offset changes when DST begins or ends.

---

#TimezoneHandling #DateFormatting #Globalization #AIAgents #Scheduling #AgenticAI #LearnAI #AIEngineering