Agent reminders

An agent can leave a reminder for itself: "check this deployment again in 20 minutes", "see whether the customer has answered by tomorrow morning". When the reminder is due, the same session continues with a turn that starts with the agent's own note, so it picks up with the full conversation behind it.

Reminders are optional and off by default. Most agents never need them; turn them on for the agent that waits on something slow (a job, a deployment, a reply).

Turn them on

Open Build → Agents, pick the agent and go to Configure → Runtime → Reminders. Switch Reminders on. Once on, the agent is offered three tools in session conversations (never in stateless calls):

Tool	What it does
reminder_set	Schedules a one-time reminder. Takes delay_seconds or at (an ISO 8601 time), a message (1 to 1000 characters) and an optional reason.
reminder_list	Lists the reminders this session is still waiting for.
reminder_cancel	Cancels one of this session's reminders by id.

The agent's prompt gets a short Reminders section explaining the tools and the limits. A refused reminder_set returns a short reason to the agent; it does not fail the turn.

Settings

Setting	Default
Minimum delay	60 s	The shortest wait the agent may ask for.
Furthest ahead	72 h	How far in the future a reminder may be.
Waiting at once, per session	3	Reminders one session may hold at the same time.
Total per session	20	Every reminder a session ever created counts, so a reminder that keeps re-arming itself stops.
Run class	deferred	The run class of the wake-up turn.
When the session is busy	postpone	postpone keeps the reminder waiting until the session is free; skip drops it.
After untrusted content	approve	See Safety setting.
Extra instructions	none	Up to 2000 characters, added to the reminders section of the prompt.

Operator ceilings clamp these values (see Limits).

What happens when one is due

A reminder is an ordinary scheduled run of the session. Its channel is reminder and its id is the run id (run_…).

• It runs unattended, as the person whose turn set it, on the same agent version.
• The owner and token checks apply when it wakes: if the token was revoked or the owner was disabled, the run fails.
• If reminders were turned off for the agent in the meantime, the run fails with "Reminders are turned off for this agent."
• If the session is waiting on an approval or on its budget, the reminder is postponed or skipped, per When the session is busy.
• A waiting run expires after the deferred-wait ceiling.
• The agent's default callback is used for reminder runs, like for any run without its own.

A reminder fires once. The agent can set another one during the wake-up turn to check again.

Safety setting

Once a turn has read tool results or other outside content, a new reminder is treated with extra care, because that content could be trying to steer the agent. After untrusted content decides what happens:

Value	Effect
approve (default)	The new reminder needs approval. In an interactive turn the person is asked. In an unattended turn the agent's human-in-the-loop unattended setting decides: deny refuses it, pause waits for an approval, allow sets it.
deny	The reminder is refused.
allow	The reminder is set without a question.

Re-arming the reminder that woke the turn (same message) is always allowed. reminder_list and reminder_cancel never need approval; reminder_set otherwise follows the agent's tool approval policy.

Where people see reminders

Sessions tab. Every turn is a run and every run belongs to a session, so there is no longer a Sessions / Background runs switch. A row shows the session's active run (scheduled, queued or running, with a stop button) and a small clock icon when the session has waiting reminders. A trigger's Runs link opens the sessions list filtered by that trigger. The session drawer has a collapsible Runs block and, when relevant, a reminder line with Fire now and Cancel.

Reminders view. A Sessions | Reminders switch appears only for agents that have reminders on or have ever set one. The Reminders view lists the next fire time, the message, the session and its owner, and the status; you can cancel one, cancel all, or fire one now, and open a detail drawer.

Playground and session page. A Reminders tab shows only when it is relevant. The wake-up turn is shown as a muted reminder card, not as a user message.

Portals. A small strip above the composer lists waiting reminders with Cancel; the wake-up turn is a reminder card, and a clock icon marks it in the history.

API

Reminders are listed and cancelled over the client API; they are created only by the agent.

curl "$BASE/api/client/v1/agents/sessions/$SESSION_ID/reminders?status=active" \
  -H "Authorization: Bearer $TOKEN"

curl -X DELETE "$BASE/api/client/v1/agents/sessions/$SESSION_ID/reminders/$REMINDER_ID" \
  -H "Authorization: Bearer $TOKEN"

status is active (default) or all. An agent.reminder object has id, object, agent, session_id, status, fire_at (epoch seconds), message, reason, set_by_run, chain, created_at, completed_at and error.

The wake-up turn is marked in the session events: user.message carries origin and reminder, and session.status_running has trigger: reminder. Transcript messages carry the same origin and reminder fields. The run's channel is reminder.

The next console-sdk release adds client.agents.sessions.reminders.list(sessionId, { status }) and .cancel(sessionId, reminderId).

Limits

Platform operators set ceilings with environment variables; an agent's settings can only be stricter.

Variable	Default
AGENT_REMINDERS_ENABLED	true	false turns the feature off platform-wide: no agent is offered the tools and due reminders are not run.
AGENT_REMINDER_MIN_DELAY_SECONDS	60	Minimum 30.
AGENT_REMINDER_MAX_HORIZON_HOURS	168	1 to 720.
AGENT_REMINDER_MAX_ACTIVE_PER_SESSION	10
AGENT_REMINDER_MAX_FIRES_PER_SESSION	100

Tenant quotas maxActiveAgentReminders (waiting reminders) and maxAgentRemindersPerDay (created in the last 24 hours) apply on top.

Not included

Recurring reminders and email or mobile notifications are not part of this feature.