Reminder tool for self-scheduling hosted agents

Let hosted agents schedule themselves to run again at a future time using the built-in reminder_preview toolbox tool.

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

The reminder_preview tool enables a hosted agent to schedule itself to run again at a future time. Use this pattern when the agent decides during a run that it needs to follow up later, such as to check back on a long-running task or to prompt the user for a status update.

When the agent calls the reminder tool, it specifies a delay in minutes. After that delay, Foundry re-invokes the same agent on the same conversation. The agent can then continue its work, check on external systems, or prompt the user.

The reminder tool is available only for hosted agents. You can’t use the reminder tool with prompt agents. To use the reminder tool, create a toolbox that includes the reminder_preview tool, then attach the toolbox to a hosted agent.

Prerequisites

• A Foundry project with a deployed model.
• A hosted agent. See Create your first hosted agent.
• Azure Developer CLI (azd) installed and authenticated. See Install the Azure Developer CLI.

How the reminder tool works

The reminder tool takes the following arguments:

Argument	Type	Range	Description
minutes	integer	1–43,200	The number of minutes to wait before re-invoking the agent.
input	string	—	Instructions for what the agent needs to do when it’s invoked by the reminder.

When the agent calls the tool, it decides how long to delay based on its reasoning. Foundry then creates a scheduled routine that fires after the specified delay and re-invokes the same hosted agent on the same conversation. This approach preserves context across invocations, unlike regular routines that start new conversations.

Add the reminder tool to a toolbox

The reminder tool is connectionless. You don’t need to configure any external service or authentication.

Configure the hosted agent

After you create the toolbox, configure your hosted agent to use it. In the agent manifest, add the toolbox endpoint under resources:

# agent.yaml
name: reminder-agent
model_deployment: gpt-4.1
instructions: |
  You are a helpful assistant. When the user asks you to follow up later,
  use the schedule_reminder tool to re-invoke yourself after the specified time.
resources:
  - kind: toolbox
    url: https://{project-endpoint}/agents/toolboxes/reminder-toolbox/mcp?version=1

Example scenario: Polling for task completion

A common scenario is polling an external system for task completion. In this pattern, the agent:

1. Receives a user request to start a long-running task.
2. Calls an external API to start the task and receives a task ID.
3. Uses the reminder tool to schedule a follow-up in 15 minutes.
4. When the reminder fires, the agent checks the task status.
5. If the task is still running, the agent schedules another reminder.
6. When the task completes, the agent notifies the user.

To enable this behavior, include instructions in your agent manifest:

# agent.yaml
name: task-monitor
model_deployment: gpt-4.1
instructions: |
  You help users monitor long-running tasks.
  
  When a user asks you to start a task:
  1. Call the start_task tool with the user's parameters.
  2. Note the task_id in your response.
  3. Use the schedule_reminder tool to check back in 15 minutes.
  
  When you're re-invoked by a reminder:
  1. Call the check_status tool with the task_id.
  2. If the task is still running, schedule another reminder for 10 minutes.
  3. If the task is complete, summarize the results for the user.
resources:
  - kind: toolbox
    url: https://{project-endpoint}/agents/toolboxes/my-toolbox/mcp?version=1

The model decides when and how to use the reminder tool based on these instructions. You don’t need to write code to handle the reminder invocation.

Limitations

• Hosted agents only. The reminder tool is available only for hosted agents. You can’t use it with prompt agents.
• Same conversation. Reminders re-invoke the agent on the same conversation. They don’t start new conversations.
• Minimum delay. The minimum delay is 1 minute.
• Maximum delay. The maximum delay is 43,200 minutes (30 days).

Related content

• Use toolboxes with agents
• Automate agents with routines
• Build your first hosted agent