> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

export const ZonePivot = ({group, options = [], defaultValue, label = "Choose an experience"}) => {
  const values = options.map(option => option.id);
  const optionKey = options.map(option => `${option.id}:${option.title}`).join("|");
  const [activePivot, setActivePivot] = useState(defaultValue || values[0]);
  const slugify = value => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
  const resolvePivot = () => {
    if (typeof window === "undefined") return defaultValue || values[0];
    const params = new URLSearchParams(window.location.search);
    const requested = params.get("pivots");
    if (requested) {
      const requestedIds = requested.split(",").map(value => value.trim()).filter(Boolean);
      const match = requestedIds.find(id => values.includes(id));
      if (match) return match;
    }
    const hash = window.location.hash.replace(/^#/, "");
    if (hash) {
      const match = options.find(option => option.id === hash || slugify(option.title) === hash);
      if (match) return match.id;
    }
    try {
      const stored = window.localStorage.getItem(`foundry-zone-pivot:${group}`);
      if (values.includes(stored)) return stored;
    } catch {
      return defaultValue || values[0];
    }
    return defaultValue || values[0];
  };
  const publishPivotChange = value => {
    if (typeof window === "undefined") return;
    window.dispatchEvent(new CustomEvent("foundry-zone-pivot-change", {
      detail: {
        group,
        value
      }
    }));
  };
  const syncTableOfContents = () => {
    if (typeof window === "undefined") return;
    window.requestAnimationFrame(() => {
      const toc = document.getElementById("table-of-contents-content");
      if (!toc) return;
      const links = Array.from(toc.querySelectorAll('a[href^="#"]'));
      for (const link of links) {
        const item = link.closest("li");
        const rawId = link.getAttribute("href")?.slice(1);
        if (!item || !rawId) continue;
        let id = rawId;
        try {
          id = decodeURIComponent(rawId);
        } catch {}
        item.style.display = document.getElementById(id) ? "" : "none";
      }
    });
  };
  useEffect(() => {
    const resolvedPivot = resolvePivot();
    setActivePivot(resolvedPivot);
    publishPivotChange(resolvedPivot);
    window.setTimeout(syncTableOfContents, 0);
  }, [group, defaultValue, values.join("|"), optionKey]);
  const selectPivot = value => {
    setActivePivot(value);
    if (typeof window !== "undefined") {
      try {
        window.localStorage.setItem(`foundry-zone-pivot:${group}`, value);
      } catch {}
      const url = new URL(window.location.href);
      const current = url.searchParams.get("pivots");
      const preserved = current ? current.split(",").map(id => id.trim()).filter(id => id && !values.includes(id)) : [];
      url.searchParams.set("pivots", [...preserved, value].join(","));
      window.history.replaceState(null, "", `${url.pathname}${url.search}${url.hash}`);
    }
    publishPivotChange(value);
    window.setTimeout(syncTableOfContents, 0);
  };
  if (options.length < 2) return null;
  return <div className="not-prose my-6 border-b border-slate-200 pb-3 dark:border-slate-800">
      <div className="mb-2 text-xs font-semibold uppercase tracking-wide text-slate-500 dark:text-slate-400">
        {label}
      </div>
      <div className="flex flex-wrap gap-2" role="tablist" aria-label={label}>
        {options.map(option => {
    const selected = option.id === activePivot;
    return <button key={option.id} type="button" role="tab" aria-selected={selected} onClick={() => selectPivot(option.id)} className={`rounded-md border px-3 py-1.5 text-sm font-medium transition ${selected ? "border-slate-900 bg-slate-900 text-white shadow-sm dark:border-slate-100 dark:bg-slate-100 dark:text-slate-950" : "border-slate-200 bg-white text-slate-700 hover:border-slate-400 hover:text-slate-950 dark:border-slate-700 dark:bg-slate-950 dark:text-slate-200 dark:hover:border-slate-500"}`}>
              {option.title}
            </button>;
  })}
      </div>
    </div>;
};

export const ZoneContent = ({group, value, options = [], values = [], defaultValue, children}) => {
  const optionKey = options.map(option => `${option.id}:${option.title}`).join("|");
  const [activePivot, setActivePivot] = useState(defaultValue || values[0]);
  const slugify = value => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
  const resolvePivot = () => {
    if (typeof window === "undefined") return defaultValue || values[0];
    const params = new URLSearchParams(window.location.search);
    const requested = params.get("pivots");
    if (requested) {
      const requestedIds = requested.split(",").map(value => value.trim()).filter(Boolean);
      const match = requestedIds.find(id => values.includes(id));
      if (match) return match;
    }
    const hash = window.location.hash.replace(/^#/, "");
    if (hash) {
      const match = options.find(option => option.id === hash || slugify(option.title) === hash);
      if (match) return match.id;
    }
    try {
      const stored = window.localStorage.getItem(`foundry-zone-pivot:${group}`);
      if (values.includes(stored)) return stored;
    } catch {
      return defaultValue || values[0];
    }
    return defaultValue || values[0];
  };
  useEffect(() => {
    setActivePivot(resolvePivot());
  }, [group, defaultValue, values.join("|"), optionKey]);
  useEffect(() => {
    const onPivotChange = event => {
      if (event.detail?.group === group && values.includes(event.detail.value)) {
        setActivePivot(event.detail.value);
      }
    };
    window.addEventListener("foundry-zone-pivot-change", onPivotChange);
    return () => window.removeEventListener("foundry-zone-pivot-change", onPivotChange);
  }, [group, values.join("|")]);
  if (activePivot !== value) return null;
  return <>{children}</>;
};

<Info>
  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](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
</Info>

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.

<Info>
  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.
</Info>

## Prerequisites

* A [Foundry project](../../../how-to/create-projects) with a deployed model.
* A hosted agent. See [Create your first hosted agent](/agents/quickstart-hosted-agent).
* Azure Developer CLI (`azd`) installed and authenticated. See [Install the Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd).

## 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](/agents/use-routines) 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.

<ZonePivot group="azd__foundry-portal__programming-language-csharp__programming-language-javascript__programming-language-python__programming-language-rest" options={[{"id": "foundry-portal", "title": "Foundry Portal"}, {"id": "programming-language-python", "title": "Python"}, {"id": "programming-language-csharp", "title": "C#"}, {"id": "programming-language-javascript", "title": "JavaScript"}, {"id": "programming-language-rest", "title": "REST"}, {"id": "azd", "title": "Azure Developer CLI"}]} defaultValue="foundry-portal" />

<ZoneContent group="azd__foundry-portal__programming-language-csharp__programming-language-javascript__programming-language-python__programming-language-rest" value="foundry-portal" options={[{"id": "foundry-portal", "title": "Foundry Portal"}, {"id": "programming-language-python", "title": "Python"}, {"id": "programming-language-csharp", "title": "C#"}, {"id": "programming-language-javascript", "title": "JavaScript"}, {"id": "programming-language-rest", "title": "REST"}, {"id": "azd", "title": "Azure Developer CLI"}]} values={["foundry-portal", "programming-language-python", "programming-language-csharp", "programming-language-javascript", "programming-language-rest", "azd"]} defaultValue="foundry-portal">
  <Frame>
    <img src="https://mintlify.s3.us-west-1.amazonaws.com/hobbyist-e43fa225/images/toolbox-reminder-tool.png" alt="Screenshot showing the reminder_preview tool in a toolbox in the Foundry portal." />
  </Frame>

  1. In the [Foundry portal](https://ai.azure.com), go to your project.
  2. In the left pane, select **Build & customize** > **Toolboxes**.
  3. Select **+ New** to create a toolbox, or select an existing toolbox to edit.
  4. In the toolbox editor, select **+ Add tool**.
  5. Under **Built-in tools**, select **Reminder (preview)**.
  6. Configure the tool name and description, and then select **Add**.
  7. Select **Save** to save the toolbox.

  The toolbox details page shows the **MCP endpoint**. Copy this endpoint to connect your hosted agent.
</ZoneContent>

<ZoneContent group="azd__foundry-portal__programming-language-csharp__programming-language-javascript__programming-language-python__programming-language-rest" value="programming-language-python" options={[{"id": "foundry-portal", "title": "Foundry Portal"}, {"id": "programming-language-python", "title": "Python"}, {"id": "programming-language-csharp", "title": "C#"}, {"id": "programming-language-javascript", "title": "JavaScript"}, {"id": "programming-language-rest", "title": "REST"}, {"id": "azd", "title": "Azure Developer CLI"}]} values={["foundry-portal", "programming-language-python", "programming-language-csharp", "programming-language-javascript", "programming-language-rest", "azd"]} defaultValue="foundry-portal">
  ```python theme={null}
  from azure.identity import DefaultAzureCredential
  from azure.ai.projects import AIProjectClient
  from azure.ai.projects.models import ReminderPreviewToolboxTool

  # Create Foundry project client
  endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
  project = AIProjectClient(
      endpoint=endpoint,
      credential=DefaultAzureCredential(),
  )

  # Create toolbox version with reminder tool
  toolbox_version = project.toolboxes.create_version(
      name="reminder-toolbox",
      description="Built-in reminder tool for a self-scheduling agent",
      tools=[
          ReminderPreviewToolboxTool(
              name="schedule_reminder",
              description="Schedule a reminder that re-invokes this agent at a future time.",
          ),
      ],
  )
  print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")
  print(f"MCP endpoint: {toolbox_version.mcp_endpoint}")
  ```
</ZoneContent>

<ZoneContent group="azd__foundry-portal__programming-language-csharp__programming-language-javascript__programming-language-python__programming-language-rest" value="programming-language-csharp" options={[{"id": "foundry-portal", "title": "Foundry Portal"}, {"id": "programming-language-python", "title": "Python"}, {"id": "programming-language-csharp", "title": "C#"}, {"id": "programming-language-javascript", "title": "JavaScript"}, {"id": "programming-language-rest", "title": "REST"}, {"id": "azd", "title": "Azure Developer CLI"}]} values={["foundry-portal", "programming-language-python", "programming-language-csharp", "programming-language-javascript", "programming-language-rest", "azd"]} defaultValue="foundry-portal">
  ```csharp theme={null}
  using Azure.Identity;
  using Azure.AI.Projects;

  // Create Foundry project client
  var projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";
  AIProjectClient projectClient = new(new Uri(projectEndpoint), new DefaultAzureCredential());

  // Create toolbox version with reminder tool
  var reminderTool = new ReminderPreviewToolboxTool
  {
      Name = "schedule_reminder",
      Description = "Schedule a reminder that re-invokes this agent at a future time."
  };

  ToolboxVersionObject toolboxVersion = await projectClient.Toolboxes.CreateVersionAsync(
      name: "reminder-toolbox",
      tools: [reminderTool],
      description: "Built-in reminder tool for a self-scheduling agent"
  );
  Console.WriteLine($"Created toolbox: {toolboxVersion.Name}, version: {toolboxVersion.Version}");
  Console.WriteLine($"MCP endpoint: {toolboxVersion.McpEndpoint}");
  ```
</ZoneContent>

<ZoneContent group="azd__foundry-portal__programming-language-csharp__programming-language-javascript__programming-language-python__programming-language-rest" value="programming-language-javascript" options={[{"id": "foundry-portal", "title": "Foundry Portal"}, {"id": "programming-language-python", "title": "Python"}, {"id": "programming-language-csharp", "title": "C#"}, {"id": "programming-language-javascript", "title": "JavaScript"}, {"id": "programming-language-rest", "title": "REST"}, {"id": "azd", "title": "Azure Developer CLI"}]} values={["foundry-portal", "programming-language-python", "programming-language-csharp", "programming-language-javascript", "programming-language-rest", "azd"]} defaultValue="foundry-portal">
  ```javascript theme={null}
  import { DefaultAzureCredential } from "@azure/identity";
  import { AIProjectClient } from "@azure/ai-projects";

  // Create Foundry project client
  const projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";
  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

  const toolboxVersion = await project.toolboxes.createVersion(
    "reminder-toolbox",
    [
      {
        type: "reminder_preview",
        name: "schedule_reminder",
        description: "Schedule a reminder that re-invokes this agent at a future time.",
      },
    ],
    {
      description: "Built-in reminder tool for a self-scheduling agent",
    },
  );
  console.log(`Created toolbox: ${toolboxVersion.name}, version: ${toolboxVersion.version}`);
  console.log(`MCP endpoint: ${toolboxVersion.mcpEndpoint}`);
  ```
</ZoneContent>

<ZoneContent group="azd__foundry-portal__programming-language-csharp__programming-language-javascript__programming-language-python__programming-language-rest" value="programming-language-rest" options={[{"id": "foundry-portal", "title": "Foundry Portal"}, {"id": "programming-language-python", "title": "Python"}, {"id": "programming-language-csharp", "title": "C#"}, {"id": "programming-language-javascript", "title": "JavaScript"}, {"id": "programming-language-rest", "title": "REST"}, {"id": "azd", "title": "Azure Developer CLI"}]} values={["foundry-portal", "programming-language-python", "programming-language-csharp", "programming-language-javascript", "programming-language-rest", "azd"]} defaultValue="foundry-portal">
  ```http theme={null}
  POST https://{project_endpoint}/toolboxes/reminder-toolbox/versions?api-version=v1
  Authorization: Bearer {token}
  Content-Type: application/json

  {
    "description": "Built-in reminder tool for a self-scheduling agent",
    "tools": [
      {
        "type": "reminder_preview",
        "name": "schedule_reminder",
        "description": "Schedule a reminder that re-invokes this agent at a future time."
      }
    ]
  }
  ```

  <Note>
    Use token scope `https://ai.azure.com/.default` when getting the bearer token.
  </Note>

  The response includes the `mcp_endpoint`. Connect your hosted agent to this endpoint.
</ZoneContent>

<ZoneContent group="azd__foundry-portal__programming-language-csharp__programming-language-javascript__programming-language-python__programming-language-rest" value="azd" options={[{"id": "foundry-portal", "title": "Foundry Portal"}, {"id": "programming-language-python", "title": "Python"}, {"id": "programming-language-csharp", "title": "C#"}, {"id": "programming-language-javascript", "title": "JavaScript"}, {"id": "programming-language-rest", "title": "REST"}, {"id": "azd", "title": "Azure Developer CLI"}]} values={["foundry-portal", "programming-language-python", "programming-language-csharp", "programming-language-javascript", "programming-language-rest", "azd"]} defaultValue="foundry-portal">
  Create a toolbox manifest file:

  ```yaml theme={null}
  # reminder-toolbox.yaml
  description: Built-in reminder tool for a self-scheduling agent
  tools:
    - type: reminder_preview
      name: schedule_reminder
      description: Schedule a reminder that re-invokes this agent at a future time.
  ```

  Create the toolbox:

  ```bash theme={null}
  azd ai toolbox create reminder-toolbox --from-file reminder-toolbox.yaml
  ```

  The command prints the toolbox MCP endpoint. Connect your hosted agent to this endpoint.
</ZoneContent>

## 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`:

```yaml theme={null}
# 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:

```yaml theme={null}
# 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](/agents/toolbox)
* [Automate agents with routines](/agents/use-routines)
* [Build your first hosted agent](/agents/quickstart-hosted-agent)