Current Time
Tell the model today’s date, or the current hour, in a time zone you pick. Use it when an agent answers questions that depend on when they are asked, such as “what’s due this week”, which a model can’t work out from its training data.
While Pydantic AI Harness is on 0.x releases, the API may change between minor releases; when it does, deprecation warnings and release-note migration guidance tell you (or your agent) exactly how to upgrade. See the version policy.
pip install pydantic-ai-harness
uv add pydantic-ai-harness
from pydantic_ai import Agent
from pydantic_ai_harness import CurrentTime
agent = Agent('anthropic:claude-opus-5-5', capabilities=[CurrentTime(timezone='Europe/Amsterdam')])
The model’s instructions then include a line such as Today's date is Friday, 2026-01-02 (Europe/Amsterdam).
| Field | Default | Meaning |
|---|---|---|
timezone | datetime.UTC | An IANA time zone name such as 'Europe/Amsterdam', or a tzinfo. A name is looked up in the system time zone database, or the tzdata package where there is none (Windows, minimal containers). An unknown name raises ZoneInfoNotFoundError when the capability is built |
precision | 'date' | 'date' states the weekday and date; 'hour' states the hour as well: The current time is within the hour starting 2026-01-02T14:00+01:00 (Friday, Europe/Amsterdam). |
id | 'current_time' | Keys the instruction block, so a change can be appended to the message history. None or '' means the default |
In an agent spec, timezone takes a zone name: - CurrentTime: {timezone: Europe/Amsterdam}, loaded with custom_capability_types=[CurrentTime].
The time is read from the timestamp the run gives the request it is about to send. When the date (or hour) moves on during a conversation, the new value is appended to the message history instead of rewriting the instructions, so the provider can keep serving the conversation so far from its prompt cache. With precision='date' that is at most one update per day; with 'hour', one per hour of conversation. There is no finer precision: text that changes on every request belongs in the user prompt or a tool.
The capability reads no clock of its own, only the request’s timestamp, so it is safe in workflow code under durable execution, where Temporal’s sandbox rejects clock reads.
CurrentTime emits no spans of its own. The text it adds is part of the request’s instructions, which an instrumented agent records on the model request span.
Two CurrentTime on one agent share the default id and merge into one, with the later one’s settings. To state the time in two zones, give the second its own id.
See the source.
Bases: AbstractCapability[AgentDepsT]
Tell the model the current date, or the current hour, in a time zone you pick.
The time is the timestamp of the request being sent, so the capability reads no clock of its own. When it moves on during a conversation, the new value is appended to the message history rather than rewriting the instructions, which keeps the cached prompt prefix.
Keys the instruction block, which appending a changed value to the history needs.
None or '' means the default, current_time.
An IANA time zone name such as 'Europe/Amsterdam', or a tzinfo.
A name is looked up in the system time zone database, or the tzdata package where there is none (Windows,
minimal containers). A tzinfo such as datetime.UTC needs neither.
Type: str | tzinfo Default: UTC
'date' states the weekday and date. 'hour' also states the hour, adding an update to the history every
hour of a conversation.
Type: Literal[‘date’, ‘hour’] Default: 'date'
def get_instructions() -> Callable[[RunContext[AgentDepsT]], InstructionPart | None]
Return the current date or hour, read from the request being sent.
Callable[[RunContext[AgentDepsT]], InstructionPart | None]