Use routines

--- title: “Automate agents with routines” description: “Create, manage, and monitor routines that trigger agents on a schedule, at a specific time, or in response to an external event.” manager: mcleans ms.service: microsoft-foundry ms.subservice: foundry-agent-service ms.topic: how-to ms.date: 08/27/2026 author: zhuoqunli ms.author: zhuoqunli ms.custom:

• dev-focus
• doc-kit-assisted
• references_regions

ai-usage: ai-assisted

Automate agents with routines

A routine is a named automation rule that triggers an agent on a schedule, at a specific time, or in response to an external event. You define what fires the routine (the trigger) and what agent to invoke (the action). Microsoft 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, the Python SDK, .NET SDK, JavaScript SDK, or the Azure Developer CLI.

All routine operations are on the data plane under your project endpoint.

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.

• A prompt agent or hosted agent. Workflow agents aren’t supported. By default, a routine invokes the agent by using the agent identity. If the agent has tools that require delegated user access, explicitly select the routine creator’s identity when you create the routine.

Routines are available in all Foundry regions except the following. Confirm that your Foundry project isn’t provisioned in one of these regions before you create a routine:

• UK West
• Switzerland West
• Japan West
• UAE North
• Norway East

Routines work with projects secured by a virtual network. Because a routine uses the project’s existing agent invocation path, it inherits the project’s network configuration and doesn’t require extra networking setup. For more information, see Set up private networking for Foundry Agent Service.

Routines don’t support customer-managed key (CMK) encryption. Don’t use routines for workloads that require CMK protection.

Create and test a scheduled routine

For the fastest path to a working routine, use the scheduled routine example and verify the complete lifecycle:

1. Create a recurring scheduled routine that invokes your agent.
2. Dispatch the routine manually instead of waiting for its schedule.
3. Inspect the run history and confirm that the run completes.
4. Delete the routine after you finish testing.

Choose a trigger or task

After the scheduled routine succeeds, choose the trigger or management task that fits your scenario.

Goal	Use this section
Run once at a future time	Timer trigger
Respond to an opened or closed issue	GitHub issue trigger
Respond to a new channel message	Teams message trigger
Pause, resume, inspect, update, or remove routines	Enable and disable a routine and List and retrieve routines
Check action and trigger request fields	Action fields and Trigger fields
Diagnose a routine that doesn’t create, fire, or complete	Troubleshooting

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.
custom	Event-based trigger from an external provider. The teams provider fires when a new message is posted to a watched Microsoft Teams channel.

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 an agent through the Responses API. Provide either the agent name or endpoint ID.
invoke_agent_invocations_api	Invokes an agent through the Invocations API. Provide either the agent name or endpoint ID.

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

Choose a dispatch identity

Every routine uses the agent identity by default. This default applies to schedule, timer, GitHub issue, and Teams event routines. The agent’s permissions determine which resources its tools can access.

If the agent has tools that require delegated user access, explicitly opt in to creator identity when you create the routine. Creator identity means only the Microsoft Entra identity of the person or service principal that creates the routine. It isn’t the identity of the agent creator, agent publisher, connection creator, a later routine editor, or another end user.

Set the top-level authorization.identity field to "creator" in a REST create request or JavaScript create options. In Python, pass RoutineAuthorization(identity="creator"). Omitting authorization, or setting the identity to "agent", uses the default agent identity.

The following examples create a disabled routine and retrieve it to confirm that authorization.identity is stored as "creator". Successful creation and retrieval confirm the saved configuration, not compatibility with every delegated tool. Check each tool’s authentication requirements and the creator’s permissions and consent separately.

The authorization setting is accepted only when you create a routine. An update ignores it. To switch an existing routine between agent and creator identity, delete and recreate the routine with the required authorization.identity value.

Creator identity has these constraints:

• The routine delegates only the routine creator’s identity. You can’t supply an arbitrary user identity at dispatch time.
• The creator must have access to every delegated resource the agent’s tools use. If that access or consent is removed, those tool calls fail.
• Recreating the routine as a different principal changes the routine creator identity.
• Authentication for an event trigger’s connector connection is separate from the identity used to dispatch the agent. The authorization object doesn’t change the connection identity.

Create a routine

A routine definition specifies a trigger (when to fire) and an action (which agent to run and through which API). A routine 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 or a message being posted to a Microsoft Teams channel. 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.

The connector connection authenticates with the external system independently of the routine’s dispatch identity. If the connection owner loses access to the connected resource, the trigger stops firing. Selecting creator identity for dispatch doesn’t change the connector connection identity.

Routines support two event-based triggers: the github_issue trigger and the custom trigger with the teams provider.

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.

When an issue event fires, the GitHub issue payload replaces action.input. The configured input applies only to manual test dispatches.

Teams message trigger

A custom trigger fires on an event from an external provider. The teams provider supports the on_new_channel_message event, which fires when a new message is posted to a watched Microsoft Teams channel. When the trigger fires, Foundry forwards the Teams message payload to the agent as its input, so the agent can respond to the message.

The trigger requires a Microsoft Teams connector connection. Foundry provisions the connection in your account’s connector namespace and uses it to authenticate to Teams. The connection_id in the trigger’s parameters references this connection. For more about connector connections, see Add managed MCP servers powered by connector namespaces.

The parameters object scopes the trigger to a single Teams channel. Set thread_type to channel, group_id to the ID of the Teams team that contains the channel, and channel_id to the ID of the channel to watch. You can obtain the team and channel IDs from Microsoft Teams or Microsoft Graph. The authenticated Teams connection must have access to the specified team and channel.

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	Conditional	The project-scoped agent name. Specify exactly one of agent_name or agent_endpoint_id. Maximum 256 characters.
agent_endpoint_id	string	Conditional	The legacy hosted-agent endpoint ID. Specify exactly one of agent_name or agent_endpoint_id.
input	JSON value	No	The input passed to the agent. For github_issue and custom Teams triggers, the event payload overwrites this value when an event fires, so it applies only to manual test dispatches.
conversation	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	Conditional	The project-scoped agent name. Specify exactly one of agent_name or agent_endpoint_id. Maximum 256 characters.
agent_endpoint_id	string	Conditional	The legacy hosted-agent endpoint ID. Specify exactly one of agent_name or agent_endpoint_id.
input	JSON value	No	The input passed to the agent. For github_issue and custom Teams triggers, the event 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.

Dispatch authorization

Dispatch authorization is a top-level routine creation field, not an action field.

Field	Type	Required	Description
authorization.identity	string	No	The identity used to invoke the agent. The default is "agent". Set it to "creator" only when the agent’s tools require delegated access from the routine creator. This field is ignored when you update an existing routine.

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	No	A future ISO 8601 timestamp with an explicit UTC offset, for example, "2030-09-01T09:00:00Z". SDKs use a timezone-aware date-time value. Set at explicitly for a usable one-time timer.

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.

Custom (Teams) trigger fields

Field	Type	Required	Description
type	string	Yes	Must be "custom".
provider	string	Yes	The external provider that emits the event. Use "teams" for Microsoft Teams.
event_name	string	Yes	The provider event that fires the routine. For the teams provider, use "on_new_channel_message".
parameters	object	Yes	Provider-specific settings that scope the trigger.

For the teams provider, parameters accepts the following fields:

Parameter	Type	Required	Description
connection_id	string	Yes	The project connection that authenticates to Microsoft Teams.
thread_type	string	Yes	The Teams thread type. Use "channel" for a channel message.
group_id	string	Yes	The ID of the Teams team (group) that contains the channel.
channel_id	string	Yes	The ID of the Teams channel to watch.

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.

Troubleshooting

Issue	Resolution
A tool call fails because it requires delegated user access.	Check the tool’s authentication requirements, permissions, and consent. To opt in to creator identity, create a new routine with authorization.identity set to "creator" through REST, Python, or JavaScript. A saved creator-identity setting doesn’t confirm that the tool supports delegated access through routines.
A routine REST request returns HTTP 400 without an API version.	Include api-version=v1 in the request URL.
An event trigger stops firing after an identity or permission change.	Confirm that the connector connection is still connected and that its owner can access the configured repository, team, or channel. Connector authentication is separate from routine dispatch identity.
The routine feature isn’t available in the project.	Confirm that the project is in a supported region. If Routines doesn’t appear in the Foundry portal, the feature isn’t enabled for the region or subscription.
The scheduled routine is rejected or fires at an unexpected time.	Use a five-field cron expression with an interval of at least five minutes. Set time_zone to the intended IANA or Windows time zone identifier.
A GitHub or Teams event doesn’t fire the routine.	Complete connector consent, confirm that the connection is connected, and verify that the authenticated identity can access the configured repository, team, and channel.
The downstream agent call times out.	Inspect the run history for the last dispatch error. Each attempt has a 30-second downstream timeout and follows the documented retry policy.
A manual dispatch fails.	Omit payload to use the configured action input. If you include payload, match its type to the routine action and provide input as a JSON value. Also confirm that the action specifies exactly one of agent_name or agent_endpoint_id.

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

Routines have 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.
• Agent types. Routines support prompt agents and hosted agents. They don’t support workflow agents. The agent-scheduled reminder tool is available only for hosted agents.
• Routine and trigger types. Routines can be one-shot (timer), recurring (schedule), or event-based. Supported event triggers are github_issue and custom with the teams provider. Other routine and trigger types aren’t supported.
• Action types. The only action is invoking one Foundry agent. Use invoke_agent_responses_api with a prompt agent or a hosted agent that exposes the Responses protocol. Use invoke_agent_invocations_api with a hosted agent that exposes the Invocations protocol.
• Dispatch identity. Every routine uses agent identity by default. Creator identity is an explicit create-time opt-in for agent tools that require delegated user access. It always represents the principal that creates the routine, not the agent creator or another user. You can’t change the dispatch identity by updating the routine.
• Network and encryption. Routines support projects secured by a virtual network and inherit the project’s network configuration. Routines don’t support customer-managed key (CMK) encryption.
• 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 aren’t available in UK West, Switzerland West, Japan West, UAE North, or Norway East. 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?api-version=v1 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

• JavaScript routine samples
• Create and configure agents
• Use toolboxes with agents