Architecture: Date Handling in AI Platform Engineering Agents

Date: 2025-11-05

Agents with Enhanced Date Handling

1. PagerDuty

File: agents/pagerduty/agent_pagerduty/protocol_bindings/a2a_server/agent.py
Why: Incident management, on-call schedules - heavily date-dependent
Guidelines: Calculate date ranges for incidents and on-call queries

2. Jira

File: agents/jira/agent_jira/protocol_bindings/a2a_server/agent.py
Why: Issue tracking with created/updated/resolved dates
Guidelines: Convert relative dates to YYYY-MM-DD format for JQL queries

3. Splunk

File: agents/splunk/agent_splunk/protocol_bindings/a2a_server/agent.py
Why: Log searches always require time ranges
Guidelines: Convert relative time to Splunk time syntax (earliest/latest parameters)

4. ArgoCD

File: agents/argocd/agent_argocd/protocol_bindings/a2a_server/agent.py
Why: Application deployments and sync status queries by date
Guidelines: Use current date for filtering applications and resources

5. Backstage

File: agents/backstage/agent_backstage/protocol_bindings/a2a_server/agent.py
Why: Catalog entity searches and filtering
Guidelines: Filter catalog entities by creation/modification date

6. Confluence

File: agents/confluence/agent_confluence/protocol_bindings/a2a_server/agent.py
Why: Document searches by creation/modification date
Guidelines: Find recently updated or created pages

7. GitHub

File: agents/github/agent_github/protocol_bindings/a2a_server/agent.py
Why: Issues, PRs, and commits often filtered by date
Guidelines: Filter GitHub resources using current date as reference

8. Komodor

File: agents/komodor/agent_komodor/protocol_bindings/a2a_server/agent.py
Why: Kubernetes events, audit logs, and issues with time ranges
Guidelines: Calculate time ranges for "today's issues" or "last hour's events"

9. Slack

File: agents/slack/agent_slack/protocol_bindings/a2a_server/agent.py
Why: Message history searches by time
Guidelines: Search messages with time-based filters

10. Webex

File: agents/webex/agent_webex/protocol_bindings/a2a_server/agent.py
Why: Message and room searches by time
Guidelines: Filter messages and rooms by timestamp

How It Works

Automatic Date Injection (ALL Agents)

Every agent sees this at the start of their system prompt:

## Current Date and Time

Today's date: Sunday, October 26, 2025
Current time: 15:30:45 UTC
ISO format: 2025-10-26T15:30:45+00:00

Use this as the reference point for all date calculations...

Enhanced Guidelines (Enabled Agents)

When include_date_handling=True is set, agents also receive:

## Important Notes

- The current date and time are provided at the top of these instructions
- Use the provided current date as the reference point for all date calculations
- For queries involving 'today', 'tomorrow', 'yesterday', or other relative dates, calculate from the provided current date
- Convert relative dates to absolute dates (YYYY-MM-DD format) before calling API tools

Plus service-specific guidelines in additional_guidelines.

Example Queries

PagerDuty

"Show me incidents from today"
"Who is on-call tomorrow?"
"List all incidents from last week"

Jira

"Show issues created this week"
"Find bugs resolved yesterday"
"Issues updated in the last 7 days"

Splunk

"Search logs from the last hour"
"Show errors from today"
"Find warnings from last 24 hours"

GitHub

"Show PRs merged today"
"Find issues created this month"
"Recent commits from this week"

Adding to New Agents

To enable enhanced date handling for a new agent:

SYSTEM_INSTRUCTION = scope_limited_agent_instruction(
    service_name="MyService",
    service_operations="manage time-sensitive operations",
    additional_guidelines=[
        "Your service-specific guidelines here",
        "When filtering by date, use current date provided above"
    ],
    include_error_handling=True,
    include_date_handling=True  # <-- Add this line
)

Or for agents using build_system_instruction:

from ai_platform_engineering.utils.prompt_templates import DATE_HANDLING_NOTES

SYSTEM_INSTRUCTION = build_system_instruction(
    agent_name="MY AGENT",
    agent_purpose="...",
    response_guidelines=[...],
    important_notes=DATE_HANDLING_NOTES,  # <-- Add this
    graceful_error_handling=graceful_error_handling_template("MyService")
)

Example Usage

Before (Would have required adding a tool):

User: "Show me incidents from today"
Agent: [Would need to call a get_current_datetime tool first]
Agent: [Would receive 2025-10-26]
Agent: [Would then call get_incidents with since=2025-10-26]

After (Automatic Injection):

User: "Show me incidents from today"
Agent: [Uses date/time auto-injected in system prompt: October 26, 2025]
Agent: [Directly calls get_incidents with since=2025-10-26]

How to Enable for Time-Sensitive Agents

For agents that frequently handle date-based queries:

SYSTEM_INSTRUCTION = scope_limited_agent_instruction(
    service_name="MyService",
    service_operations="manage time-sensitive operations",
    include_date_handling=True  # <-- Add this
)

Or for agents using build_system_instruction:

from ai_platform_engineering.utils.prompt_templates import DATE_HANDLING_NOTES

SYSTEM_INSTRUCTION = build_system_instruction(
    agent_name="MY AGENT",
    agent_purpose="...",
    response_guidelines=[...],
    important_notes=DATE_HANDLING_NOTES,  # <-- Add this
    graceful_error_handling=graceful_error_handling_template("MyService")
)

Example Queries

PagerDuty

"Show me incidents from today"
"Who is on-call tomorrow?"
"List all incidents from last week"

Jira

"Show issues created this week"
"Find bugs resolved yesterday"
"Issues updated in the last 7 days"

Splunk

"Search logs from the last hour"
"Show errors from today"
"Find warnings from last 24 hours"

GitHub

"Show PRs merged today"
"Find issues created this month"
"Recent commits from this week"

Future Enhancements

Potential improvements:

User timezone detection from request headers
Multi-timezone display
Date range validation
Enhanced natural language date parsing

Files Modified

ai_platform_engineering/utils/a2a_common/base_langgraph_agent.py
ai_platform_engineering/utils/prompt_templates.py
ai_platform_engineering/agents/pagerduty/agent_pagerduty/protocol_bindings/a2a_server/agent.py
ai_platform_engineering/agents/jira/agent_jira/protocol_bindings/a2a_server/agent.py
ai_platform_engineering/agents/splunk/agent_splunk/protocol_bindings/a2a_server/agent.py
ai_platform_engineering/agents/argocd/agent_argocd/protocol_bindings/a2a_server/agent.py
ai_platform_engineering/agents/backstage/agent_backstage/protocol_bindings/a2a_server/agent.py
ai_platform_engineering/agents/confluence/agent_confluence/protocol_bindings/a2a_server/agent.py
ai_platform_engineering/agents/github/agent_github/protocol_bindings/a2a_server/agent.py
ai_platform_engineering/agents/komodor/agent_komodor/protocol_bindings/a2a_server/agent.py
ai_platform_engineering/agents/slack/agent_slack/protocol_bindings/a2a_server/agent.py
ai_platform_engineering/agents/webex/agent_webex/protocol_bindings/a2a_server/agent.py

Migration Notes

No migration needed! This feature is:

✅ Backward compatible
✅ Automatically enabled for all agents
✅ Non-breaking change
✅ Optional enhanced guidelines via include_date_handling=True

Existing agents will automatically benefit from this feature without any code changes.

Date Handling in AI Platform Engineering Agents

This guide explains how agents automatically receive current date/time context and how to properly handle date-related queries.

Automatic Date Injection

All agents using BaseLangGraphAgent automatically receive the current date and time in their system prompt. This happens in the _get_system_instruction_with_date() method, which prepends date context before the agent's custom system instruction.

What Gets Injected

Every agent automatically receives:

## Current Date and Time

Today's date: Sunday, October 26, 2025
Current time: 15:30:45 UTC
ISO format: 2025-10-26T15:30:45+00:00

Use this as the reference point for all date calculations. When users say "today", "tomorrow", "yesterday", or other relative dates, calculate from this date.

Benefits

No Tool Calls Needed: Agents don't need to call an external tool to get the current date
Reduced Latency: Date information is immediately available in the prompt
Consistent Behavior: All agents automatically have temporal awareness
Simple Implementation: Works for all agents inheriting from BaseLangGraphAgent

Enabling Date Handling Guidelines for Specific Agents

For agents that frequently work with dates (e.g., PagerDuty, Jira, incident management), enable additional date handling guidelines:

from ai_platform_engineering.utils.prompt_templates import scope_limited_agent_instruction

SYSTEM_INSTRUCTION = scope_limited_agent_instruction(
    service_name="PagerDuty",
    service_operations="get information about incidents, services, and schedules",
    additional_guidelines=[
        "When querying incidents or on-call schedules, calculate date ranges based on the current date provided above",
        "Always convert relative dates (today, tomorrow, this week) to absolute dates in YYYY-MM-DD format before calling API tools"
    ],
    include_error_handling=True,
    include_date_handling=True  # <-- Enable date handling guidelines
)

When include_date_handling=True, the agent receives these additional instructions:

"The current date and time are provided at the top of these instructions"
"Use the provided current date as the reference point for all date calculations"
"For queries involving 'today', 'tomorrow', 'yesterday', or other relative dates, calculate from the provided current date"
"Convert relative dates to absolute dates (YYYY-MM-DD format) before calling API tools"

Example: PagerDuty Agent with Date Handling

# ai_platform_engineering/agents/pagerduty/agent_pagerduty/protocol_bindings/a2a_server/agent.py

from ai_platform_engineering.utils.a2a_common.base_langgraph_agent import BaseLangGraphAgent
from ai_platform_engineering.utils.prompt_templates import scope_limited_agent_instruction

class PagerDutyAgent(BaseLangGraphAgent):
    """PagerDuty Agent for incident and schedule management."""

    SYSTEM_INSTRUCTION = scope_limited_agent_instruction(
        service_name="PagerDuty",
        service_operations="get information about incidents, services, and schedules",
        additional_guidelines=[
            "Perform actions like creating, updating, or resolving incidents",
            "When querying incidents or on-call schedules, calculate date ranges based on the current date provided above",
            "Always convert relative dates (today, tomorrow, this week) to absolute dates in YYYY-MM-DD format before calling API tools"
        ],
        include_error_handling=True,
        include_date_handling=True  # Enable date handling guidelines
    )

How It Works

1. Agent Initialization

When an agent is initialized, the graph is created with the date-enhanced prompt:

# In BaseLangGraphAgent._setup_mcp_and_graph()
self.graph = create_react_agent(
    self.model,
    tools,
    checkpointer=memory,
    prompt=self._get_system_instruction_with_date(),  # <-- Uses date-enhanced prompt
    response_format=(
        self.get_response_format_instruction(),
        self.get_response_format_class()
    ),
)

2. Date Context Generation

The _get_system_instruction_with_date() method:

Gets the current UTC time
Formats it in multiple ways (human-readable, ISO 8601)
Prepends it to the agent's system instruction

3. LLM Processing

When the LLM receives a query like "show me incidents from today", it:

Sees the current date at the top of the system prompt
Calculates that "today" means "2025-10-26"
Calls the API with since=2025-10-26T00:00:00Z

Common Date Query Patterns

Today

User: "Show me incidents from today"
Agent calculates: 2025-10-26
API call: since=2025-10-26T00:00:00Z&until=2025-10-26T23:59:59Z

Yesterday

User: "Who was on-call yesterday?"
Agent calculates: 2025-10-25
API call: since=2025-10-25T00:00:00Z&until=2025-10-25T23:59:59Z

Last Week

User: "Show incidents from last week"
Agent calculates: Previous Sunday to Saturday
API call: since=2025-10-20T00:00:00Z&until=2025-10-26T23:59:59Z

Tomorrow

User: "Who is on-call tomorrow?"
Agent calculates: 2025-10-27
API call: since=2025-10-27T00:00:00Z&until=2025-10-27T23:59:59Z

Custom Date Handling

If you need custom date handling logic, you can:

Override _get_system_instruction_with_date() in your agent class
Add timezone-specific logic
Include additional temporal context

Example:

class MyCustomAgent(BaseLangGraphAgent):
    def _get_system_instruction_with_date(self) -> str:
        """Custom date injection with timezone support."""
        now_utc = datetime.now(ZoneInfo("UTC"))
        now_local = datetime.now(ZoneInfo("America/New_York"))

        date_context = f"""## Current Date and Time

UTC: {now_utc.strftime("%A, %B %d, %Y %H:%M:%S")}
Local (America/New_York): {now_local.strftime("%A, %B %d, %Y %H:%M:%S")}

"""
        return date_context + self.get_system_instruction()

Troubleshooting

Agent Not Using Current Date

Problem: Agent seems to use incorrect dates or doesn't understand "today"

Solution:

Verify agent inherits from BaseLangGraphAgent
Check that include_date_handling=True if needed
Review agent logs to see the actual system prompt being used

Timezone Issues

Problem: Dates are off by hours or days

Solution:

Current implementation uses UTC by default
Override _get_system_instruction_with_date() to add timezone-specific context
Ensure API calls use UTC timestamps or specify timezone explicitly

Date Format Mismatches

Problem: API rejects date format

Solution:

Add explicit format instructions in additional_guidelines
Example: "Always use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ"

Future Enhancements

Potential improvements for date handling:

User Timezone Detection: Detect user's timezone from request headers
Multi-Timezone Support: Show times in multiple timezones simultaneously
Natural Language Date Parsing: Enhanced parsing of complex date expressions
Date Range Validation: Validate date ranges before API calls
Caching: Cache date calculations to avoid repetitive computations

Spec: spec.md

Agents with Enhanced Date Handling​

1. PagerDuty​

2. Jira​

3. Splunk​

4. ArgoCD​

5. Backstage​

6. Confluence​

7. GitHub​

8. Komodor​

9. Slack​

10. Webex​

How It Works​

Automatic Date Injection (ALL Agents)​

Enhanced Guidelines (Enabled Agents)​

Example Queries​

PagerDuty​

Jira​

Splunk​

GitHub​

Adding to New Agents​

Example Usage​

Before (Would have required adding a tool):​

After (Automatic Injection):​

How to Enable for Time-Sensitive Agents​

Example Queries​

PagerDuty​

Jira​

Splunk​

GitHub​

Future Enhancements​

Files Modified​

Migration Notes​

Date Handling in AI Platform Engineering Agents

Automatic Date Injection​

What Gets Injected​

Benefits​

Enabling Date Handling Guidelines for Specific Agents​

Example: PagerDuty Agent with Date Handling​

How It Works​

1. Agent Initialization​

2. Date Context Generation​

3. LLM Processing​

Common Date Query Patterns​

Today​

Yesterday​

Last Week​

Tomorrow​

Custom Date Handling​

Troubleshooting​

Agent Not Using Current Date​

Timezone Issues​

Date Format Mismatches​

Future Enhancements​

Related​

Agents with Enhanced Date Handling

1. PagerDuty

2. Jira

3. Splunk

4. ArgoCD

5. Backstage

6. Confluence

7. GitHub

8. Komodor

9. Slack

10. Webex

How It Works

Automatic Date Injection (ALL Agents)

Enhanced Guidelines (Enabled Agents)

Example Queries

PagerDuty

Jira

Splunk

GitHub

Adding to New Agents

Example Usage

Before (Would have required adding a tool):

After (Automatic Injection):

How to Enable for Time-Sensitive Agents

Example Queries

PagerDuty

Jira

Splunk

GitHub

Future Enhancements

Files Modified

Migration Notes

Automatic Date Injection

What Gets Injected

Benefits

Enabling Date Handling Guidelines for Specific Agents

Example: PagerDuty Agent with Date Handling

How It Works

1. Agent Initialization

2. Date Context Generation

3. LLM Processing

Common Date Query Patterns

Today

Yesterday

Last Week

Tomorrow

Custom Date Handling

Troubleshooting

Agent Not Using Current Date

Timezone Issues

Date Format Mismatches

Future Enhancements

Related