Automatización de agentes con rutinas (versión preliminar)

• Instale el azure-ai-projects SDK, versión 2.2.0 o posterior (versión preliminar):

  pip install "azure-ai-projects>=2.2.0"
  

  La versión 2.2.0 introduce la forma abreviada de la duración ("30m", "2h") para los activadores de temporizador.

• Instalación azure-identity para la autenticación:

  pip install azure-identity
  

• Instale el @azure/ai-projects paquete npm (versión preliminar):

  npm install @azure/ai-projects @azure/identity
  

• Instale curl o cualquier cliente HTTP.
• Instale el CLI de Azure para adquirir tokens de acceso.

• Instale la CLI para desarrolladores de Azure (azd 1.23.13 o posterior).

• Instale la extensión de rutinas (versión preliminar):

  azd extension install azure.ai.routines
  

• Inicie sesión y configure el punto de conexión de su proyecto:

  azd auth login
  export AZURE_AI_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
  

1. En Microsoft Foundry, abra el proyecto.

2. En el panel de navegación izquierdo, seleccione Rutinas.

3. Seleccione + Nueva rutina.

4. Escriba un nombre para la rutina, por ejemplo daily-summary.

5. Seleccione un agente en la lista desplegable.

6. Introduzca un Prompt que el agente ejecutará en cada invocación.

7. En Desencadenador, establezca Tipo en Programación periódica y, a continuación, elija una frecuencia (diaria o semanal) y una hora.

8. Seleccione Crear e iniciar.

   

El portal interpreta la hora en la zona horaria local del explorador. Para anclar una rutina a una zona horaria específica independientemente del explorador, créela a través de la API REST o un SDK y proporcione el time_zone campo.

Reemplace los valores de marcador de posición y, a continuación, ejecute:

PROJECT_ENDPOINT=<your-project-endpoint>   # e.g. https://<account>.services.ai.azure.com/api/projects/<project>
AGENT_NAME=<your-agent-name>

TOKEN=$(az account get-access-token \
  --resource https://ai.azure.com \
  --query accessToken -o tsv)

# Using Responses API action
curl -sS -X PUT "$PROJECT_ENDPOINT/routines/daily-summary" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Routines=V1Preview" \
  -d '{
    "description": "Runs a daily summary agent on weekday mornings.",
    "enabled": true,
    "triggers": {
      "weekday-morning": {
        "type": "schedule",
        "cron_expression": "0 7 * * 1-5",
        "time_zone": "UTC"
      }
    },
    "action": {
      "type": "invoke_agent_responses_api",
      "agent_name": "'"$AGENT_NAME"'"
    }
  }'

Para usar la acción Invocations API en su lugar, reemplace el action objeto por lo siguiente. agent_name es obligatorio; session_id es opcional.

# Using Invocations API action
curl -sS -X PUT "$PROJECT_ENDPOINT/routines/daily-summary" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Routines=V1Preview" \
  -d '{
    "description": "Runs a daily summary agent on weekday mornings.",
    "enabled": true,
    "triggers": {
      "weekday-morning": {
        "type": "schedule",
        "cron_expression": "0 7 * * 1-5",
        "time_zone": "UTC"
      }
    },
    "action": {
      "type": "invoke_agent_invocations_api",
      "agent_name": "'"$AGENT_NAME"'"
    }
  }'

Una respuesta satisfactoria devuelve HTTP 200 o 201 con el objeto de rutina, incluidas las marcas de tiempo created_at y updated_at.

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

endpoint = os.environ["PROJECT_ENDPOINT"]
agent_name = os.environ["AGENT_NAME"]

client = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())

# Using Responses API action
routine = client.beta.routines.create_or_update(
    routine_name="daily-summary",
    description="Runs a daily summary agent on weekday mornings.",
    enabled=True,
    triggers={
        "weekday-morning": {
            "type": "schedule",
            "cron_expression": "0 7 * * 1-5",  # required
            "time_zone": "UTC",                 # required
        }
    },
    action={
        "type": "invoke_agent_responses_api",
        "agent_name": agent_name,  # required
        # "conversation_id": "...",  # optional
    },
)

print(f"Routine created: {routine.name}, enabled={routine.enabled}")

# To use the Invocations API action instead:
# action={
#     "type": "invoke_agent_invocations_api",
#     "agent_name": agent_name,  # required
#     # "session_id": "...",      # optional
# }

const { AIProjectClient } = require("@azure/ai-projects");
const { DefaultAzureCredential } = require("@azure/identity");

const endpoint = process.env.PROJECT_ENDPOINT;
const agentName = process.env.AGENT_NAME;

const client = new AIProjectClient(endpoint, new DefaultAzureCredential());

// Using Responses API action
const routine = await client.beta.routines.createOrUpdate("daily-summary", {
  description: "Runs a daily summary agent on weekday mornings.",
  enabled: true,
  triggers: {
    "weekday-morning": {
      type: "schedule",
      cron_expression: "0 7 * * 1-5",  // required
      time_zone: "UTC",                 // required
    },
  },
  action: {
    type: "invoke_agent_responses_api",
    agent_name: agentName,  // required
    // conversation_id: "...",  // optional
  },
});

console.log(`Routine created: ${routine.name}, enabled=${routine.enabled}`);

// To use the Invocations API action instead:
// action: {
//   type: "invoke_agent_invocations_api",
//   agent_name: agentName,  // required
//   // session_id: "...",    // optional
// }

azd ai routine create --trigger schedule insertada no se admite en versión preliminar. Cree la rutina a partir de un manifiesto YAML en su lugar:

# routine.yaml
name: daily-summary
description: Runs a daily summary agent on weekday mornings.
enabled: true
triggers:
  weekday-morning:
    type: schedule
    cron: "0 7 * * 1-5"
    time_zone: UTC
action:
  type: invoke_agent_responses_api
  agent_name: <your-agent-name>

azd ai routine create --file routine.yaml

El intervalo mínimo entre los incendios es de cinco minutos. Establezca time_zone en una zona IANA cualquiera (por ejemplo, America/Los_Angeles); omítalo para interpretar cron en UTC.

1. Siga los pasos 1 a 6 del procedimiento anterior para abrir el cuadro de diálogo Nueva rutina y rellenar Nombre, Agente y Prompt. Use un nombre como once-on-release-day.

2. En Desencadenador, configure Tipo como Programación de una sola vez.

3. En Ejecutar en, elija la fecha y hora en que debe activarse la rutina.

4. Seleccione Crear e iniciar.

   

El valor de Ejecutar a las se interpreta en la zona horaria local del explorador. Una programación de una sola vez se activa exactamente una vez, en el momento que se elija.

# Using Responses API action
curl -sS -X PUT "$PROJECT_ENDPOINT/routines/once-on-release-day" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Routines=V1Preview" \
  -d '{
    "description": "Runs the agent once on release day.",
    "enabled": true,
    "triggers": {
      "release-day": {
        "type": "timer",
        "at": "2026-09-01T09:00:00Z"
      }
    },
    "action": {
      "type": "invoke_agent_responses_api",
      "agent_name": "'"$AGENT_NAME"'"
    }
  }'

El at campo acepta:

• Una marca de tiempo ISO 8601 con un desfase UTC explícito, por ejemplo "2026-06-01T09:00:00Z".
• Marca de tiempo local emparejada con time_zone, por ejemplo "at": "2026-09-01T09:00:00", "time_zone": "America/Los_Angeles".
• Duración positiva de la hora actual, por ejemplo "30m" (30 minutos desde ahora) o "2h" (dos horas desde ahora).

routine = client.beta.routines.create_or_update(
    routine_name="once-on-release-day",
    description="Runs the agent once on release day.",
    enabled=True,
    triggers={
        "release-day": {
            "type": "timer",
            "at": "2026-09-01T09:00:00Z",  # required
            # "time_zone": "UTC",           # optional; required when 'at' has no UTC offset
        }
    },
    action={
        "type": "invoke_agent_responses_api",
        "agent_name": agent_name,
    },
)

const routine = await client.beta.routines.createOrUpdate("once-on-release-day", {
  description: "Runs the agent once on release day.",
  enabled: true,
  triggers: {
    "release-day": {
      type: "timer",
      at: "2026-09-01T09:00:00Z",  // required
      // time_zone: "UTC",          // optional; required when 'at' has no UTC offset
    },
  },
  action: {
    type: "invoke_agent_responses_api",
    agent_name: agentName,
  },
});

Cree en línea una rutina de temporizador de una sola vez en línea:

azd ai routine create once-on-release-day \
  --trigger timer \
  --at 2026-09-01T09:00:00Z \
  --action agent-response \
  --agent-name <your-agent-name>

O bien, cree a partir de un manifiesto YAML:

# routine.yaml
name: once-on-release-day
description: Runs the agent once on release day.
enabled: true
triggers:
  release-day:
    type: timer
    time_zone: UTC
    at: 2026-09-01T09:00:00Z
action:
  type: invoke_agent_responses_api
  agent_name: <your-agent-name>

azd ai routine create --file routine.yaml

1. En Microsoft Foundry, abra el proyecto.

2. Seleccione Rutinas en el panel de navegación izquierdo.

3. Busque la rutina y selecciónela.

4. Seleccione Pausar en la parte superior derecha para pausar la rutina o seleccione Reanudar para volver a habilitar una rutina en pausa.

   

Desde la misma página, también puede:

• Seleccione Ejecutar prueba (el botón de la derecha o la entrada del menú de desbordamiento) para ejecutar la rutina inmediatamente con su indicación y agente actuales, sin esperar al siguiente desencadenador programado.
• Revisa las ejecuciones anteriores en la tabla situada debajo de los detalles de la rutina. Cada fila muestra el identificador de respuesta, cuando se desencadenó la ejecución, su duración y su estado. Use los filtros Last day, 7D, 1M o Custom para definir el ámbito del intervalo de tiempo. Seleccione un identificador de respuesta para abrir la ejecución completa.

Deshabilitar una rutina:

curl -sS -X POST "$PROJECT_ENDPOINT/routines/daily-summary:disable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: Routines=V1Preview"

Habilite una rutina:

curl -sS -X POST "$PROJECT_ENDPOINT/routines/daily-summary:enable" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: Routines=V1Preview"

Ambas operaciones devuelven el objeto de rutina actualizado.

# Disable
disabled_routine = client.beta.routines.disable("daily-summary")
print(f"Enabled: {disabled_routine.enabled}")   # False

# Enable
enabled_routine = client.beta.routines.enable("daily-summary")
print(f"Enabled: {enabled_routine.enabled}")    # True

// Disable
const disabled = await client.beta.routines.disable("daily-summary");
console.log(`Enabled: ${disabled.enabled}`);   // false

// Enable
const enabled = await client.beta.routines.enable("daily-summary");
console.log(`Enabled: ${enabled.enabled}`);    // true

# Disable
azd ai routine disable once-on-release-day

# Enable
azd ai routine enable once-on-release-day

1. Abra la rutina en Microsoft Foundry.
2. Seleccione Ejecutar prueba (el botón de la derecha o la entrada en el menú de desbordamiento junto a Pausa).

Foundry pone en cola la ejecución inmediatamente con el agente y la indicación actuales de la rutina. La nueva ejecución aparece en la tabla de ejecuciones anteriores debajo de los detalles de rutina y avanza de Queued a Completed o Failed.

Utilice la operación dispatch_async para poner en cola la ejecución. El tipo de carga útil del despacho debe coincidir con el tipo de acción de la rutina: utilice invoke_agent_responses_api para las rutinas de Responses API y invoke_agent_invocations_api para las rutinas de Invocations API.

Rutina de la API Responses — con anulación opcional de la entrada:

curl -sS -X POST "$PROJECT_ENDPOINT/routines/daily-summary:dispatch_async" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Routines=V1Preview" \
  -d '{
    "payload": {
      "type": "invoke_agent_responses_api",
      "input": "Run the daily summary for testing."
    }
  }'

Rutina de la API de invocaciones, con anulación opcional de la entrada:

curl -sS -X POST "$PROJECT_ENDPOINT/routines/my-invocations-routine:dispatch_async" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Routines=V1Preview" \
  -d '{
    "payload": {
      "type": "invoke_agent_invocations_api",
      "input": "Run the agent for testing."
    }
  }'

Respuesta:

{
  "dispatch_id": "disp-abc123",
  "action_correlation_id": "resp-xyz456",
  "task_id": "task-def789"
}

Usa el dispatch_id para encontrar la ejecución en el historial de ejecución.

Sin una anulación de la entrada:

curl -sS -X POST "$PROJECT_ENDPOINT/routines/daily-summary:dispatch_async" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Routines=V1Preview" \
  -d '{}'

# Responses API routine
result = client.beta.routines.dispatch(
    routine_name="daily-summary",
    payload={
        "type": "invoke_agent_responses_api",
        "input": "Run the daily summary for testing.",  # optional
    },
)
print(f"dispatch_id: {result.dispatch_id}")
print(f"task_id:     {result.task_id}")

# Invocations API routine
result2 = client.beta.routines.dispatch(
    routine_name="my-invocations-routine",
    payload={
        "type": "invoke_agent_invocations_api",
        "input": "Run the agent for testing.",  # optional
    },
)

// Responses API routine
const result = await client.beta.routines.dispatch("daily-summary", {
  payload: {
    type: "invoke_agent_responses_api",
    input: "Run the daily summary for testing.",  // optional
  },
});
console.log(`dispatch_id: ${result.dispatch_id}`);

// Invocations API routine
const result2 = await client.beta.routines.dispatch("my-invocations-routine", {
  payload: {
    type: "invoke_agent_invocations_api",
    input: "Run the agent for testing.",  // optional
  },
});

Ponga en cola una ejecución manual para una rutina de la API de Respuestas:

azd ai routine dispatch once-on-release-day \
  --input "Run the routine for testing."

El comando imprime el dispatch_id y el task_id. Usa el dispatch_id para encontrar la ejecución en el historial de ejecución.

1. Abra la rutina en Microsoft Foundry.
2. Las ejecuciones anteriores se muestran en la tabla de la página de detalles de la rutina. Cada fila muestra el identificador de respuesta, cuando se desencadenó la ejecución, su duración y su estado (por ejemplo , Completado o Erróneo).
3. Use los controles De último día, 7D, 1M o Intervalo personalizado encima de la tabla para filtrar la ventana de tiempo.
4. Seleccione un identificador de respuesta para abrir la ejecución completa, incluida la respuesta y los detalles del error.

Enumerar todas las ejecuciones de una rutina:

curl -sS "$PROJECT_ENDPOINT/routines/daily-summary/runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: Routines=V1Preview"

Respuesta de ejemplo:

{
  "value": [
    {
      "id": "run-abc123",
      "status": "FINISHED",
      "phase": "completed",
      "trigger_type": "schedule",
      "attempt_source": "schedule_delivery",
      "started_at": "2026-06-02T07:00:05Z",
      "ended_at": "2026-06-02T07:00:42Z",
      "dispatch_id": "disp-abc123",
      "response_id": "resp-xyz456"
    }
  ]
}

runs = client.beta.routines.list_runs("daily-summary")

for run in runs:
    print(
        f"{run.id}  phase={run.phase}  "
        f"source={run.attempt_source}  "
        f"started={run.started_at}  ended={run.ended_at}"
    )
    if run.phase == "failed":
        print(f"  error: {run.error_type} — {run.error_message}")

for await (const run of client.beta.routines.listRuns("daily-summary")) {
  console.log(`${run.id}  phase=${run.phase}  source=${run.attempt_source}`);
  if (run.phase === "failed") {
    console.log(`  error: ${run.error_type} — ${run.error_message}`);
  }
}

No se admite la enumeración del historial de ejecuciones a través de azd ai routine en la versión preliminar. Use el portal de Foundry, la API REST o un SDK para recuperar ejecuciones.

Todas las rutinas del proyecto se muestran en la página Rutinas . Seleccione cualquier rutina para ver su configuración y el historial de ejecución.

Enumerar todas las rutinas del proyecto:

curl -sS "$PROJECT_ENDPOINT/routines" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: Routines=V1Preview"

Recuperar una rutina específica:

curl -sS "$PROJECT_ENDPOINT/routines/daily-summary" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: Routines=V1Preview"

# List all routines
for r in client.beta.routines.list():
    print(f"{r.name}  enabled={r.enabled}  triggers={list(r.triggers.keys())}")

# Get a single routine
routine = client.beta.routines.get("daily-summary")
print(routine)

// List all routines
for await (const r of client.beta.routines.list()) {
  console.log(`${r.name}  enabled=${r.enabled}`);
}

// Get a single routine
const routine = await client.beta.routines.get("daily-summary");
console.log(routine);

Obtener una única rutina:

azd ai routine show once-on-release-day

No se admite listar todas las rutinas mediante azd ai routine en la versión preliminar. Use el portal de Foundry, la API REST o un SDK.

1. Abra la rutina en Microsoft Foundry.
2. Seleccione Editar.
3. Cambie la configuración del desencadenador o de la acción.
4. Haga clic en Guardar.

Vuelva a enviar la solicitud PUT con el cuerpo actualizado. Incluir todos los campos; los campos omitidos se restablecen a los valores predeterminados.

curl -sS -X PUT "$PROJECT_ENDPOINT/routines/daily-summary" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Routines=V1Preview" \
  -d '{
    "description": "Updated: runs at 08:00 UTC on weekdays.",
    "enabled": true,
    "triggers": {
      "weekday-morning": {
        "type": "schedule",
        "cron_expression": "0 8 * * 1-5",
        "time_zone": "UTC"
      }
    },
    "action": {
      "type": "invoke_agent_responses_api",
      "agent_name": "'"$AGENT_NAME"'"
    }
  }'

updated = client.beta.routines.create_or_update(
    routine_name="daily-summary",
    description="Updated: runs at 08:00 UTC on weekdays.",
    enabled=True,
    triggers={
        "weekday-morning": {
            "type": "schedule",
            "cron_expression": "0 8 * * 1-5",
            "time_zone": "UTC",
        }
    },
    action={
        "type": "invoke_agent_responses_api",
        "agent_name": agent_name,
    },
)
print(f"Updated at: {updated.updated_at}")

const updated = await client.beta.routines.createOrUpdate("daily-summary", {
  description: "Updated: runs at 08:00 UTC on weekdays.",
  enabled: true,
  triggers: {
    "weekday-morning": {
      type: "schedule",
      cron_expression: "0 8 * * 1-5",
      time_zone: "UTC",
    },
  },
  action: {
    type: "invoke_agent_responses_api",
    agent_name: agentName,
  },
});
console.log(`Updated at: ${updated.updated_at}`);

Aplicar cambios desde un manifiesto YAML:

azd ai routine update once-on-release-day --file routine.yaml

El indicador --description no se admite para las rutinas de temporizador en la versión preliminar; edite el manifiesto y vuelva a aplicarlo con --file en su lugar.

1. Abra la rutina en Microsoft Foundry.
2. Seleccione Eliminar y confirme.

curl -sS -X DELETE "$PROJECT_ENDPOINT/routines/daily-summary" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: Routines=V1Preview"

Una respuesta correcta devuelve HTTP 204 Sin contenido.

client.beta.routines.delete("daily-summary")
print("Routine deleted.")

await client.beta.routines.delete("daily-summary");
console.log("Routine deleted.");

azd ai routine delete once-on-release-day