Herramienta recordatorio para agentes de programación automática

Importante

Los elementos marcados (versión preliminar) de este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para obtener más información, vea Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

La reminder_preview herramienta permite a un agente hospedado programar su ejecución de nuevo en un futuro. Use este patrón cuando el agente decida durante una ejecución que necesite realizar un seguimiento posterior, por ejemplo, para volver a comprobar una tarea de larga duración o para solicitar al usuario una actualización de estado.

Cuando el agente llama a la herramienta de recordatorio, especifica un retraso en minutos. Después de ese retraso, Foundry vuelve a invocar al mismo agente en la misma conversación. Entonces, el agente puede continuar su trabajo, comprobar el estado de sistemas externos o solicitar información al usuario.

Importante

La herramienta reminder solo está disponible para agentes hospedados. No se puede utilizar la herramienta de recordatorio con agentes de respuesta inmediata. Para usar la herramienta recordatorio, cree un cuadro de herramientas que incluya la reminder_preview herramienta y, a continuación, adjunte el cuadro de herramientas a un agente hospedado.

Prerequisites

Funcionamiento de la herramienta recordatorio

La herramienta de recordatorios toma los siguientes argumentos:

Argumento Tipo Alcance Description
minutes integer 1–43,200 Número de minutos que se deben esperar antes de volver a invocar al agente.
input string Instrucciones para lo que el agente debe hacer cuando el aviso lo invoca.

Cuando el agente invoca la herramienta, decide cuánto tiempo debe retrasarse en función de su razonamiento. A continuación, Foundry crea una rutina programada que se activa después del retraso especificado y vuelve a invocar al mismo agente hospedado en la misma conversación. Este enfoque conserva el contexto entre invocaciones, a diferencia de las rutinas normales que inician nuevas conversaciones.

Adición de la herramienta de recordatorio a un cuadro de herramientas

La herramienta de recordatorio no tiene conexión. No es necesario configurar ningún servicio externo ni autenticación.

Captura de pantalla que muestra la herramienta reminder_preview en un cuadro de herramientas en el portal de Foundry.

  1. En el portal de Foundry, vaya a su proyecto.
  2. En el panel izquierdo, seleccione Compilar y personalizar>cuadros de herramientas.
  3. Seleccione + Nuevo para crear un cuadro de herramientas o seleccione un cuadro de herramientas existente para editar.
  4. En el editor del cuadro de herramientas, seleccione + Agregar herramienta.
  5. En Herramientas integradas, seleccione Recordatorio (versión preliminar) .
  6. Configure el nombre y la descripción de la herramienta y, a continuación, seleccione Agregar.
  7. Seleccione Guardar para guardar el cuadro de herramientas.

La página de detalles del cuadro de herramientas muestra el punto de conexión de MCP. Copie este punto de conexión para conectar su agente alojado.

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}")
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}");
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}`);
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 el ámbito del token https://ai.azure.com/.default al obtener el token de portador.

La respuesta incluye el mcp_endpoint. Conecte el agente hospedado a este punto de conexión.

Cree un archivo de manifiesto del cuadro de herramientas:

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

Cree el cuadro de herramientas:

azd ai toolbox create reminder-toolbox --from-file reminder-toolbox.yaml

El comando imprime el punto de conexión MCP del cuadro de herramientas. Conecte el agente hospedado a este punto de conexión.

Configuración del agente hospedado

Después de crear el cuadro de herramientas, configure el agente hospedado para usarlo. En el manifiesto del agente, añada el punto de conexión de Toolbox en 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

Escenario de ejemplo: Sondeo de finalización de tareas

Un escenario habitual es consultar un sistema externo para comprobar si una tarea ha finalizado. En este patrón, el agente:

  1. Recibe una solicitud de usuario para iniciar una tarea de larga duración.
  2. Llama a una API externa para iniciar la tarea y recibe un identificador de tarea.
  3. Usa la herramienta recordatorio para programar un seguimiento en 15 minutos.
  4. Cuando se activa el aviso, el agente comprueba el estado de la tarea.
  5. Si la tarea sigue en ejecución, el agente programa otro aviso.
  6. Cuando se completa la tarea, el agente notifica al usuario.

Para habilitar este comportamiento, incluya instrucciones en el manifiesto del agente:

# 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

El modelo decide cuándo y cómo usar la herramienta de recordatorio en función de estas instrucciones. No es necesario escribir código para controlar la invocación de recordatorio.

Limitations

  • Solo para agentes hospedados. La herramienta reminder solo está disponible para agentes hospedados. No se puede utilizar con agentes de solicitud.
  • Misma conversación. Los recordatorios vuelven a invocar al agente en la misma conversación. No inician nuevas conversaciones.
  • Retraso mínimo. El retraso mínimo es de 1 minuto.
  • Retraso máximo. El retraso máximo es de 43 200 minutos (30 días).