Use routines

--- 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: mcleans ms.service: microsoft-foundry ms.subservice: foundry-agent-service ms.topic: how-to ms.date: 07/08/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.

A routine is a named automation rule that triggers an agent on a schedule or at a specific time. You define what fires the routine (the trigger) and what agent to invoke (the action). Foundry queues the invocation, runs the agent, and stores a run record you can inspect later.

This article shows you how to create, manage, and monitor routines by using the Foundry portal, the REST API, and the Python and JavaScript SDKs.

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 the following 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.
github_issue	Event-based trigger that fires when an issue is opened or closed in a watched GitHub repository.

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.

For required and optional fields of each action type, see Action fields.

Routines can’t invoke an agent that requires an end-user identity to be passed at run time. A routine runs unattended, so there’s no signed-in user to delegate. Use routines only with agents that authenticate through their own configured identity, not on-behalf-of the caller.

Prerequisites

• An active Microsoft Foundry project with at least one agent deployed.
• Foundry User role or higher on the project scope.

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). The preview supports exactly one trigger entry.

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.

Event-based triggers

An event-based trigger runs an agent when an external event occurs, such as a GitHub issue being opened. Event-based triggers rely on a connector connection that Foundry provisions in your account’s connector namespace and uses to authenticate to the external system. The trigger references this connection by ID. For more about connector connections, see Add managed MCP servers powered by connector namespaces.

An event-based routine runs under the identity of the routine creator. The connection uses the routine creator’s identity to authenticate with the external system, such as GitHub, so the routine watches and acts on that system with that person’s access. If the routine creator loses access to the connected resource, the routine stops firing.

The preview supports the github_issue event-based trigger.

Non-Microsoft tools including third-party MCP servers available in the Foundry Tools Catalog (“Third-Party Tools”) are Non-Microsoft Products under your agreement governing use of Azure. When you connect to a Third-Party Tool, you do so at your own risk. You’re responsible for any terms and charges for Third-Party Tools. Microsoft has no responsibility to you or others in relation to your use of Third-Party Tools. Carefully review and track the Third-Party Tools you add to your MCP client.

Some of your information and data (such as authentication keys and prompt content) might be passed to the Third-Party Tool, or your MCP client might receive data from the Third-Party Tool. Review all data shared with Third-Party Tools and stay aware of third-party practices for data retention and location. You’re responsible for managing whether your data flows outside your organization’s Azure compliance and geographic boundaries.

MCP implementations are vulnerable to attacks, cascading failures, and loss of human oversight. To mitigate these risks, vet MCP servers for security and reliability, follow Microsoft’s recommendations and industry best practices, and implement approval mechanisms to monitor cascading behaviors.

GitHub issue trigger

A github_issue trigger fires when an issue is opened or closed in a watched GitHub repository. When the trigger fires, Foundry forwards the GitHub issue payload to the agent as its input, so the agent can triage or act on the issue.

The trigger relies on a GitHub connector connection. Foundry provisions the connection to GitHub in your account’s connector namespace and authenticates to GitHub through it. The connection_id you set on the trigger references this connection. Each tab shows how to create the connection and the routine that uses it. For more about connector connections, see Add managed MCP servers powered by connector namespaces.

The issue_event field accepts opened or closed only.

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.
input	string	No	The input passed to the agent. For a github_issue trigger, the GitHub issue payload overwrites this value when an event fires, so it applies only to manual test dispatches.
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.
input	string	No	The input passed to the agent. For a github_issue trigger, the GitHub issue payload overwrites this value when an event fires, so it applies only to manual test dispatches.
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 step lets you verify that the routine reaches your agent correctly.

View run history

Run history records every time a routine fires and the outcome of each attempt.

List and retrieve routines

Update a routine

To change a routine’s trigger or action, send a new create-or-update request with the same name. This operation replaces the stored definition.

Delete a routine

When you delete a routine, you remove it and stop all future trigger deliveries. The process preserves existing run records.

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.

GitHub issue trigger fields

Field	Type	Required	Description
type	string	Yes	Must be "github_issue".
connection_id	string	Yes	The project connection that authenticates to GitHub. Maximum 256 characters.
owner	string	Yes	The GitHub owner or organization that scopes which issues can fire the trigger. Maximum 128 characters.
repository	string	Yes	The GitHub repository that scopes which issues can fire the trigger. Maximum 128 characters.
issue_event	string	Yes	The GitHub issue event that fires the routine. Supported values: opened, closed.

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

If retries are exhausted, the run is marked failed with the last dispatch error.

A successful run means the downstream API accepted the dispatch request. It doesn’t guarantee that asynchronous work started by the agent has completed.

Retry and timeout defaults

• The default delivery policy is three 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.

Let an agent schedule its own reminders

Routines let an external trigger start an agent. A hosted agent can also schedule itself to run again at a future time by calling the built-in reminder_preview toolbox tool. 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.

The reminder tool is available only for hosted agents. You can’t use the reminder tool with prompt agents.

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 or check on external systems.

For full setup instructions, usage examples, and how reminders differ from routines, see Reminder tool for self-scheduling agents.

Known issues and limitations

This 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. The supported triggers are timer (one-shot), schedule (cron-based recurring), and github_issue (event-based). The agent-scheduled reminder tool is available only for hosted agents.
• 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 you don’t see Routines 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. 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

• Create a Foundry project
• Create and configure agents
• Model Context Protocol (MCP)
• Use toolboxes with agents