---
title: “Automate agents with routines (preview)”
description: “Create, manage, and monitor routines that automatically trigger agents on a schedule or at a specific time in Microsoft Foundry.”
manager: nitinme
ms.service: microsoft-foundry
ms.subservice: foundry-agent-service
ms.topic: how-to
ms.date: 06/01/2026
author: zhuoqunli
ms.author: zhuoqunli
ms.custom:
- dev-focus
- doc-kit-assisted
- references_regions
ai-usage: ai-assisted
Automate agents with routines (preview)
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. Routines are in preview. Send the Foundry-Features: Routines=V1Preview header on every REST call. All routine operations are on the data plane under your project endpoint.
Supported trigger types
Routines support two time-based trigger types:
| Trigger type | Description |
|---|
schedule | Recurring trigger defined by a cron expression. Minimum interval is five minutes. |
timer | One-shot trigger that fires at a specific future date/time or after a duration. |
Supported action types
Each routine specifies exactly one action that runs when the routine fires. Two action types are supported:
| Action type | Description |
|---|
invoke_agent_responses_api | Invokes the agent through the Responses API. Provide either the agent name or endpoint ID. |
invoke_agent_invocations_api | Invokes the agent through the Invocations API. Requires the endpoint-scoped agent identifier. |
Prerequisites
The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.
Routines are available in a subset of regions in preview. Confirm that your Foundry project is provisioned in one of the supported regions before you create a routine:
- East US
- East US 2
- West US
- West US 2
- West Central US
- North Central US
- Sweden Central
- Japan East
Create a routine
A routine definition specifies a trigger (when to fire) and an action (which agent to run and through which API). Exactly one trigger entry is supported in preview.
Schedule trigger
A schedule trigger fires repeatedly on a cron expression. The service enforces a minimum interval of five minutes.
Timer trigger
A timer trigger fires once at a specific future date and time, or after a duration from now.
Action fields
Each routine specifies exactly one action. The two supported action types have different required and optional fields.
Responses API action (invoke_agent_responses_api)
Invokes the agent through the Responses API.
| Field | Type | Required | Description |
|---|
type | string | Yes | Must be "invoke_agent_responses_api". |
agent_name | string | Yes | The project-scoped agent name. Maximum 256 characters. |
conversation_id | string | No | An existing conversation to continue during the dispatch. Maximum 256 characters. |
Invocations API action (invoke_agent_invocations_api)
Invokes the agent through the Invocations API.
| Field | Type | Required | Description |
|---|
type | string | Yes | Must be "invoke_agent_invocations_api". |
agent_name | string | Yes | The project-scoped agent name. Maximum 256 characters. |
session_id | string | No | An existing hosted-agent session to continue during the dispatch. Maximum 256 characters. |
Enable and disable a routine
Routines start enabled if you set "enabled": true at creation. You can pause a routine without deleting it.
Test a routine manually
Queue a one-off run without waiting for the trigger to fire. This lets you verify that the routine reaches your agent correctly.
View run history
Run history records every time a routine fired and the outcome of each attempt.
List and retrieve routines
Update a routine
To change a routine’s trigger or action, issue a new create-or-update request with the same name. The operation replaces the stored definition.
Delete a routine
Deleting a routine removes it and stops all future trigger deliveries. Existing run records are preserved.
Trigger fields
Schedule trigger fields
| Field | Type | Required | Description |
|---|
type | string | Yes | Must be "schedule". |
cron_expression | string | Yes | A 5-field cron expression. The service enforces a minimum interval of five minutes. |
time_zone | string | Yes | An IANA or Windows time zone identifier, for example "UTC" or "America/Los_Angeles". |
Timer trigger fields
| Field | Type | Required | Description |
|---|
type | string | Yes | Must be "timer". |
at | string | Yes | A future timer expression. Accepts an ISO 8601 timestamp with an explicit UTC offset (for example, "2026-06-01T09:00:00Z"), a local timestamp paired with time_zone, or a positive duration from now (for example, "30m" or "2h"). |
time_zone | string | No | An IANA or Windows time zone identifier. Required when at is a local timestamp without a UTC offset. |
Dispatch behavior and retry policy
When a trigger fires or you call :dispatch_async manually, Foundry acknowledges that the run was enqueued. The acknowledgment doesn’t mean the downstream agent call has finished. Use the run state, telemetry, or the returned dispatch_id to confirm completion.
Downstream call outcomes
The delivery worker waits for the downstream invoke_agent_responses_api or invoke_agent_invocations_api HTTP call to finish before marking the run.
| Downstream HTTP result | Routine run behavior |
|---|
| 2xx | Run is marked completed and downstream dispatch identifiers are recorded. |
| 408, 429, or 5xx | Treated as retryable while attempts remain. |
| Other 4xx (for example, 400) | Treated as terminal and the run is marked failed. |
| Request timeout or transient service-invocation failure | Treated as retryable while attempts remain. |
Retry and timeout defaults
- The default delivery policy is 3 total attempts with exponential backoff starting at 1 second and capped at 5 seconds.
- The downstream HTTP request has a per-attempt timeout of 30 seconds. Queueing time, retry backoff, and worker concurrency limits aren’t included in that per-request timeout.
Known issues and limitations
The preview has the following known issues and limitations:
- One trigger and one action per routine. Each routine supports exactly one entry in the
triggers map and one action. To run multiple agents or multiple schedules, create separate routines.
- Trigger types. Only
timer (one-shot) and schedule (cron-based recurring) triggers are supported. Event-based triggers aren’t available in preview.
- Action types. The only action is invoking one Foundry agent through the Responses API or Invocations API.
- Schedule minimum interval. A
schedule trigger fires at most once every five minutes. Cron expressions that resolve to a shorter interval are rejected.
- Regional availability. Routines are available only in the regions listed under Prerequisites. If Routines isn’t visible in the Foundry portal navigation, the feature isn’t enabled for your region or subscription.
- Use
:dispatch_async for manual dispatch. Only the POST .../routines/{routineName}:dispatch_async route is part of the public contract. The legacy :dispatch route isn’t supported for customer use.
- Acknowledgment isn’t completion. A
:dispatch_async response acknowledges that the run was enqueued, not that the downstream agent call finished. Use the run state, telemetry, or the returned dispatch_id to observe final delivery.
- Per-attempt timeout. The downstream HTTP request to the agent has a per-attempt timeout of 30 seconds. Queueing time, retry backoff, message-bus delivery time, and worker concurrency limits aren’t included in that timeout. Requests that exceed the per-attempt timeout are retried per the retry and timeout defaults, and the routine run is marked failed if all attempts time out.
- Successful delivery doesn’t guarantee end-to-end completion. A completed routine run means the downstream API returned success for the dispatch request. It doesn’t guarantee that asynchronous work started by the agent has finished.
Related content