Edit

Automate agents with routines (preview)

Important

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

Note

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.

Prerequisites

  • An active Microsoft Foundry project with at least one agent deployed.

  • Foundry User role or higher on the project scope.

    Important

    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.

  • An agent that authenticates through its configured identity. 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.

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

  • Install the azure-ai-projects SDK, version 2.3.0 or later:

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

  • Install azure-identity for authentication:

    pip install azure-identity

  • Install the coherent routines preview package set and Azure Identity. Stable 2.0.1 packages don't include routines:

    dotnet add package Azure.AI.Projects --version 2.1.0-beta.4
dotnet add package Azure.AI.Projects.Agents --version 2.1.0-beta.4
dotnet add package Azure.AI.Extensions.OpenAI --version 2.1.0-beta.4
dotnet add package Azure.Identity

  • Install the @azure/ai-projects npm package. Routine operations are in preview:

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

  • Use Node.js 22 or later.

  • Install curl or any HTTP client.
  • Install the Azure CLI to acquire access tokens.

  • Install the Azure Developer CLI (azd 1.23.13 or later).

  • Install the routines extension (preview):

    azd extension install azure.ai.routines

  • Sign in and set your project endpoint:

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

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.
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. In the preview, 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.

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.

  1. In Microsoft Foundry, open your project.

  2. In the left navigation, select Routines.

  3. Select + New routine.

  4. Enter a Name for the routine, such as daily-summary.

  5. Select an Agent from the dropdown.

  6. Enter a Prompt for the agent to run on each invocation.

  7. Under Trigger, set Type to Recurring schedule, and then choose a Frequency (Daily or Weekly) and a Time.

  8. Select Create & start.

    Screenshot of the New routine dialog with the Recurring schedule trigger type selected, showing Frequency set to Daily and Time set to 9:00 AM.

The portal interprets the Time in your browser's local time zone. To pin a routine to a specific time zone independently of the browser, create it through the REST API or an SDK and supply the time_zone field.

Note

If Routines isn't visible in the navigation, the feature isn't enabled for your region or subscription. Contact your account team to request access.

Replace the placeholder values, and then run the command:

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"'",
      "input": "Summarize activity from the last 24 hours."
    }
  }'

To use the Invocations API action instead, replace the action object with the following. agent_name is required; session_id is optional.

# 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"'",
      "input": "Summarize activity from the last 24 hours."
    }
  }'

A successful response returns HTTP 200 or 201 with the routine object, including created_at and updated_at timestamps.

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
from datetime import datetime, timezone

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
        "input": "Summarize activity from the last 24 hours.",  # optional
        # "conversation": "...",  # 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
# }

using Azure.Identity;
using Azure.AI.Projects;

var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
var agentName = Environment.GetEnvironmentVariable("AGENT_NAME");

var projectClient = new AIProjectClient(new Uri(projectEndpoint), new DefaultAzureCredential());
var routinesClient = projectClient.Routines;

// Using Responses API action
var action = new AgentResponsesApiRoutineAction
{
    AgentName = agentName,
    Input = BinaryData.FromObjectAsJson("Summarize activity from the last 24 hours."),
};

var routineOptions = new ProjectsRoutineOptions(
    action: action,
    description: "Runs a daily summary agent on weekday mornings.",
    enabled: true);

routineOptions.Triggers.Add("weekday-morning", new ScheduleRoutineTrigger(
    cronExpression: "0 7 * * 1-5",  // required
    timeZone: "UTC"                  // required
));

ProjectsRoutine routine = await routinesClient.CreateOrUpdateAsync(
    name: "daily-summary",
    options: routineOptions);

Console.WriteLine($"Routine created: {routine.Name}, enabled={routine.IsEnabled}");

// To use the Invocations API action instead:
// var action = new AgentInvocationsApiRoutineAction
// {
//     AgentName = agentName,
//     // SessionId = "...",
// };

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

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

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

// Using Responses API action
const routine = await project.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
    input: "Summarize activity from the last 24 hours.",  // optional
    // conversation: "...",  // 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
// }

Inline azd ai routine create --trigger schedule isn't supported in preview. Create the routine from a YAML manifest instead:

# 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>
  input: Summarize activity from the last 24 hours.

azd ai routine create --file routine.yaml

Set time_zone to any IANA zone (for example, America/Los_Angeles); omit it to interpret cron in UTC.

Timer trigger

A timer trigger fires once at a specific future date and time, or after a duration from now.

  1. Follow steps 1 through 6 in the previous procedure to open the New routine dialog and fill in Name, Agent, and Prompt. Use a name such as once-on-release-day.

  2. Under Trigger, set Type to One-time schedule.

  3. Under Run at, pick the date and time when the routine should fire.

  4. Select Create & start.

    Screenshot of the New routine dialog with the One-time schedule trigger type selected, showing a date picker and a time picker under Run at.

The Run at value is interpreted in your browser's local time zone. A one-time schedule fires exactly once, at the time you pick.

# 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"'",
      "input": "Run the release-day tasks."
    }
  }'

Set at to an ISO 8601 timestamp with an explicit UTC offset, for example, "2026-06-01T09:00:00Z".

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": datetime(2026, 9, 1, 9, 0, tzinfo=timezone.utc),
        }
    },
    action={
        "type": "invoke_agent_responses_api",
        "agent_name": agent_name,
        "input": "Run the release-day tasks.",  # optional
    },
)

var action = new AgentResponsesApiRoutineAction
{
    AgentName = agentName,
    Input = BinaryData.FromObjectAsJson("Run the release-day tasks."),
};

var routineOptions = new ProjectsRoutineOptions(
    action: action,
    description: "Runs the agent once on release day.",
    enabled: true);

routineOptions.Triggers.Add("release-day", new TimerRoutineTrigger(
    at: DateTimeOffset.Parse("2026-09-01T09:00:00Z")
));

ProjectsRoutine routine = await routinesClient.CreateOrUpdateAsync(
    name: "once-on-release-day",
    options: routineOptions);

const routine = await project.beta.routines.createOrUpdate("once-on-release-day", {
  description: "Runs the agent once on release day.",
  enabled: true,
  triggers: {
    "release-day": {
      type: "timer",
      at: new Date("2026-09-01T09:00:00Z"),
    },
  },
  action: {
    type: "invoke_agent_responses_api",
    agent_name: agentName,
    input: "Run the release-day tasks.",  // optional
  },
});

Create a one-shot timer routine inline:

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

Or create from a YAML manifest:

# 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>
  input: Run the release-day tasks.

azd ai routine create --file routine.yaml

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.

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 or Microsoft Teams, 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 two event-based triggers: the github_issue trigger and the custom trigger with the teams provider.

Important

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.

To connect GitHub in the portal, follow the portal steps in Add managed MCP servers powered by connector namespaces. After the connection exists, create the routine that references it through the REST API, an SDK, or the Azure Developer CLI, as shown in the other tabs.

First create the GitHub connector connection, then reference it by name in the trigger's connection_id field.

Step 1: Acquire tokens. You need a catalog token to discover the connector and an Azure Resource Manager token to create the connection.

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

Step 2: Discover the GitHub connector to get its entityId. The catalog is served from eastus regardless of your project's region.

RESPONSE=$(curl -sS -X POST "https://eastus.api.azureml.ms/asset-gallery/v1.0/tools" \
  -H "Authorization: Bearer $CATALOG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "type",             "operator": "eq", "values": ["tools"] },
      { "field": "annotations/name", "operator": "eq", "values": ["github"] }
    ],
    "pageSize": 1
  }')
ENTITY_ID=$(echo "$RESPONSE" | jq -r '.value[0].entityId')

Step 3: Create the project connection. Set target to the literal https://placeholder; the platform rewrites it after consent.

SUBSCRIPTION_ID=<your-subscription-id>
RESOURCE_GROUP=<your-resource-group>
ACCOUNT_NAME=<your-foundry-account-name>
PROJECT_NAME=<your-project-name>
CONNECTION_NAME=github-conn

CONNECTION_URL="https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$ACCOUNT_NAME/projects/$PROJECT_NAME/connections/$CONNECTION_NAME?api-version=2025-04-01-preview"

curl -sS -X PUT "$CONNECTION_URL" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "authType": "OAuth2",
      "category": "RemoteTool",
      "connectorName": "github",
      "target": "https://placeholder",
      "metadata": {
        "type": "gateway_connector",
        "toolEntityId": "'"$ENTITY_ID"'"
      }
    }
  }'

Step 4: Authorize GitHub. Get a one-time OAuth consent link, then open it in a browser and sign in to GitHub.

CALLER_OID=$(az ad signed-in-user show --query id -o tsv)
CALLER_TID=$(az account show --query tenantId -o tsv)

curl -sS -X POST "$CONNECTION_URL&action=listConsentLinks" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": [{
      "objectId":      "'"$CALLER_OID"'",
      "parameterName": "token",
      "redirectUrl":   "https://ai.azure.com/nextgen/authConsentPopup",
      "tenantId":      "'"$CALLER_TID"'"
    }]
  }' | jq -r '.value[0].link'

For the complete connector reference, see Add managed MCP servers powered by connector namespaces.

Step 5: Create the routine that references the connection by name.

curl -sS -X PUT "$PROJECT_ENDPOINT/routines/on-issue-opened" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Routines=V1Preview" \
  -d '{
    "description": "Triages a GitHub issue when it is opened in the watched repository.",
    "enabled": true,
    "triggers": {
      "on-issue": {
        "type": "github_issue",
        "connection_id": "github-conn",
        "owner": "your-org",
        "repository": "your-repo",
        "issue_event": "opened"
      }
    },
    "action": {
      "type": "invoke_agent_responses_api",
      "agent_name": "'"$AGENT_NAME"'",
      "input": "Triage this GitHub issue."
    }
  }'

Note

For a github_issue trigger, the GitHub issue payload overwrites action.input. When an issue event fires the routine, Foundry replaces the input value with the issue payload. The input you set applies only to manual test dispatches.

The Python SDK creates the routine but not the GitHub connector connection. Create the connection first in the Foundry portal, with the REST API, or with the Azure Developer CLI, then reference it by name in the trigger's connection_id field.

routine = client.beta.routines.create_or_update(
    routine_name="on-issue-opened",
    description="Triages a GitHub issue when it is opened in the watched repository.",
    enabled=True,
    triggers={
        "on-issue": {
            "type": "github_issue",
            "connection_id": "github-conn",  # required: project connection to GitHub
            "owner": "your-org",              # required
            "repository": "your-repo",        # required
            "issue_event": "opened",          # required: "opened" or "closed"
        }
    },
    action={
        "type": "invoke_agent_responses_api",
        "agent_name": agent_name,
        "input": "Triage this GitHub issue.",  # optional; omitted when the issue payload is present
    },
)

Note

For a github_issue trigger, the GitHub issue payload overwrites action.input. When an issue event fires the routine, Foundry replaces the input value with the issue payload. The input you set applies only to manual test dispatches.

The C# SDK creates the routine but not the GitHub connector connection. Create the connection first in the Foundry portal, with the REST API, or with the Azure Developer CLI. Then reference it by name in the trigger's ConnectionId property.

var action = new AgentResponsesApiRoutineAction
{
    AgentName = agentName,
    Input = BinaryData.FromObjectAsJson("Triage this GitHub issue."),  // optional; omitted when the issue payload is present
};

var routineOptions = new ProjectsRoutineOptions(
    action: action,
    description: "Triages a GitHub issue when it is opened in the watched repository.",
    enabled: true);

routineOptions.Triggers.Add("on-issue", new GitHubIssueRoutineTrigger(
    connectionId: "github-conn",      // required: project connection to GitHub
    owner: "your-org",                 // required
    repository: "your-repo",           // required
    issueEvent: GitHubIssueEvent.Opened  // required: Opened or Closed
));

ProjectsRoutine routine = await routinesClient.CreateOrUpdateAsync(
    name: "on-issue-opened",
    options: routineOptions);

Note

For a github_issue trigger, the GitHub issue payload overwrites action.Input. When an issue event fires the routine, Foundry replaces the Input value with the issue payload. The Input you set applies only to manual test dispatches.

The JavaScript SDK creates the routine but not the GitHub connector connection. Create the connection first in the Foundry portal, with the REST API, or with the Azure Developer CLI, then reference it by name in the trigger's connection_id field.

const routine = await project.beta.routines.createOrUpdate("on-issue-opened", {
  description: "Triages a GitHub issue when it is opened in the watched repository.",
  enabled: true,
  triggers: {
    "on-issue": {
      type: "github_issue",
      connection_id: "github-conn",  // required: project connection to GitHub
      owner: "your-org",             // required
      repository: "your-repo",       // required
      issue_event: "opened",         // required: "opened" or "closed"
    },
  },
  action: {
    type: "invoke_agent_responses_api",
    agent_name: agentName,
    input: "Triage this GitHub issue.",  // optional; omitted when the issue payload is present
  },
});

Note

For a github_issue trigger, the GitHub issue payload overwrites action.input. When an issue event fires the routine, Foundry replaces the input value with the issue payload. The input you set applies only to manual test dispatches.

Create the GitHub OAuth2 connection

Before you can create a GitHub issue routine, register the GitHub connector as a project connection. Use azd ai connection create with --connector-name github:

azd ai connection create github-conn \
  --connector-name github

The connection is created in an Unauthenticated state. Retrieve the consent URL and open it in a browser:

azd ai connection show github-conn

Sign in to GitHub once and authorize the application. After consent is recorded, overallStatus transitions to Connected.

Create the routine

Reference the connection by name in the routine's connection_id. Create the routine inline:

azd ai routine create on-issue-opened \
  --trigger github-issue \
  --owner your-org \
  --repository your-repo \
  --issue-event opened \
  --connection-id github-conn \
  --agent-name <your-agent-name>

Or create it from a YAML manifest:

# routine.yaml
name: on-issue-opened
description: Triages a GitHub issue when it is opened in the watched repository.
enabled: true
triggers:
  on-issue:
    type: github_issue
    connection_id: github-conn
    owner: your-org
    repository: your-repo
    issue_event: opened
action:
  type: invoke_agent_responses_api
  agent_name: <your-agent-name>

azd ai routine create on-issue-opened --file routine.yaml

Note

The agent referenced by agent_name must have a configured agent identity. The service rejects prompt-only agents when they're bound to a routine action.

Teams message trigger

A custom trigger fires on an event from an external provider. In the preview, 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.

To connect Teams in the portal, follow the portal steps in Add managed MCP servers powered by connector namespaces. After the connection exists, create the routine that references it through the REST API, an SDK, or the Azure Developer CLI, as shown in the other tabs.

First create the Teams connector connection, then reference it by name in the trigger's connection_id parameter.

Step 1: Acquire tokens. You need a catalog token to discover the connector and an Azure Resource Manager token to create the connection.

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

Step 2: Discover the Teams connector to get its entityId. The catalog is served from eastus regardless of your project's region.

RESPONSE=$(curl -sS -X POST "https://eastus.api.azureml.ms/asset-gallery/v1.0/tools" \
  -H "Authorization: Bearer $CATALOG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "type",             "operator": "eq", "values": ["tools"] },
      { "field": "annotations/name", "operator": "eq", "values": ["teams"] }
    ],
    "pageSize": 1
  }')
ENTITY_ID=$(echo "$RESPONSE" | jq -r '.value[0].entityId')

Step 3: Create the project connection. Set target to the literal https://placeholder; the platform rewrites it after consent.

SUBSCRIPTION_ID=<your-subscription-id>
RESOURCE_GROUP=<your-resource-group>
ACCOUNT_NAME=<your-foundry-account-name>
PROJECT_NAME=<your-project-name>
CONNECTION_NAME=teams-conn

CONNECTION_URL="https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$ACCOUNT_NAME/projects/$PROJECT_NAME/connections/$CONNECTION_NAME?api-version=2025-04-01-preview"

curl -sS -X PUT "$CONNECTION_URL" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "authType": "OAuth2",
      "category": "RemoteTool",
      "connectorName": "teams",
      "target": "https://placeholder",
      "metadata": {
        "type": "gateway_connector",
        "toolEntityId": "'"$ENTITY_ID"'"
      }
    }
  }'

Step 4: Authorize Teams. Get a one-time OAuth consent link, then open it in a browser and sign in with your Microsoft account.

CALLER_OID=$(az ad signed-in-user show --query id -o tsv)
CALLER_TID=$(az account show --query tenantId -o tsv)

curl -sS -X POST "$CONNECTION_URL&action=listConsentLinks" \
  -H "Authorization: Bearer $ARM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": [{
      "objectId":      "'"$CALLER_OID"'",
      "parameterName": "token",
      "redirectUrl":   "https://ai.azure.com/nextgen/authConsentPopup",
      "tenantId":      "'"$CALLER_TID"'"
    }]
  }' | jq -r '.value[0].link'

For the complete connector reference, see Add managed MCP servers powered by connector namespaces.

Step 5: Create the routine that references the connection by name.

curl -sS -X PUT "$PROJECT_ENDPOINT/routines/teams-new-message" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: Routines=V1Preview" \
  -d '{
    "description": "Invokes an agent when a new message is posted to a Teams channel.",
    "enabled": true,
    "triggers": {
      "incoming": {
        "type": "custom",
        "provider": "teams",
        "event_name": "on_new_channel_message",
        "parameters": {
          "connection_id": "teams-conn",
          "thread_type": "channel",
          "group_id": "<your-team-group-id>",
          "channel_id": "<your-channel-id>"
        }
      }
    },
    "action": {
      "type": "invoke_agent_responses_api",
      "agent_name": "'"$AGENT_NAME"'"
    }
  }'

Note

For a custom Teams trigger, the incoming Teams message payload becomes the agent input when an event fires. Any input you set on the action applies only to manual test dispatches.

The Python SDK creates the routine but not the Teams connector connection. Create the connection first in the Foundry portal, with the REST API, or with the Azure Developer CLI, then reference it by name in the trigger's connection_id parameter.

routine = client.beta.routines.create_or_update(
    routine_name="teams-new-message",
    description="Invokes an agent when a new message is posted to a Teams channel.",
    enabled=True,
    triggers={
        "incoming": {
            "type": "custom",
            "provider": "teams",
            "event_name": "on_new_channel_message",
            "parameters": {
                "connection_id": "teams-conn",   # required: project connection to Teams
                "thread_type": "channel",
                "group_id": "<your-team-group-id>",
                "channel_id": "<your-channel-id>",
            },
        }
    },
    action={
        "type": "invoke_agent_responses_api",
        "agent_name": agent_name,
    },
)

Note

For a custom Teams trigger, the incoming Teams message payload becomes the agent input when an event fires. Any input you set on the action applies only to manual test dispatches.

The JavaScript SDK creates the routine but not the Teams connector connection. Create the connection first in the Foundry portal, with the REST API, or with the Azure Developer CLI, then reference it by name in the trigger's connection_id parameter.

const routine = await project.beta.routines.createOrUpdate("teams-new-message", {
  description: "Invokes an agent when a new message is posted to a Teams channel.",
  enabled: true,
  triggers: {
    incoming: {
      type: "custom",
      provider: "teams",
      event_name: "on_new_channel_message",
      parameters: {
        connection_id: "teams-conn",   // required: project connection to Teams
        thread_type: "channel",
        group_id: "<your-team-group-id>",
        channel_id: "<your-channel-id>",
      },
    },
  },
  action: {
    type: "invoke_agent_responses_api",
    agent_name: agentName,
  },
});

Note

For a custom Teams trigger, the incoming Teams message payload becomes the agent input when an event fires. Any input you set on the action applies only to manual test dispatches.

Create the Teams connector connection first by following the azd steps in Add managed MCP servers powered by connector namespaces. After the connection exists, reference it by name in the trigger's connection_id parameter.

Because the custom trigger takes a nested parameters object, create the routine from a YAML manifest:

# routine.yaml
name: teams-new-message
description: Invokes an agent when a new message is posted to a Teams channel.
enabled: true
triggers:
  incoming:
    type: custom
    provider: teams
    event_name: on_new_channel_message
    parameters:
      connection_id: teams-conn
      thread_type: channel
      group_id: <your-team-group-id>
      channel_id: <your-channel-id>
action:
  type: invoke_agent_responses_api
  agent_name: <your-agent-name>

azd ai routine create teams-new-message --file routine.yaml

Note

The agent referenced by agent_name must have a configured agent identity. The service rejects prompt-only agents when they're bound to a routine action.

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 a github_issue trigger, the GitHub issue 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 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.

  1. In Microsoft Foundry, open your project.
  2. Select Routines in the left navigation.
  3. Find the routine and select it.
  4. Select Pause in the top right to pause the routine, or select Resume to re-enable a paused routine.

From the same page, you can also:

  • Select Test run (either the button on the right or the entry in the overflow menu) to fire the routine immediately with its current prompt and agent, without waiting for the next scheduled trigger.
  • Review past runs in the table below the routine details. Each row shows the response ID, when the run was triggered, its duration, and its state. Use the Last day, 7D, 1M, or Custom filters to scope the time range. Select a response ID to open the full run.

Disable a routine:

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

Enable a routine:

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

Both operations return the updated routine object.

# 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
ProjectsRoutine disabled = await routinesClient.DisableAsync("daily-summary");
Console.WriteLine($"Enabled: {disabled.IsEnabled}");   // false

// Enable
ProjectsRoutine enabled = await routinesClient.EnableAsync("daily-summary");
Console.WriteLine($"Enabled: {enabled.IsEnabled}");    // true

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

// Enable
const enabled = await project.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

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.

  1. Open the routine in Microsoft Foundry.
  2. Select Test run (either the button on the right or the entry in the overflow menu next to Pause).

Foundry queues the run immediately with the routine's current agent and prompt. The new run appears in the past-runs table below the routine details and progresses from Queued to Completed or Failed.

Use the dispatch_async operation to queue the run. You can omit payload to run the routine with its configured action input. If you include payload, its type must match the routine's action type: use invoke_agent_responses_api for Responses API routines and invoke_agent_invocations_api for Invocations API routines.

Payload field Type Required Description
type string Yes when payload is present Must match the routine's action type: "invoke_agent_responses_api" or "invoke_agent_invocations_api".
input JSON value Yes when payload is present Override input sent to the downstream target for testing.

Responses API routine with an input override:

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."
    }
  }'

Invocations API routine with an input override:

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."
    }
  }'

Response:

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

Use the dispatch_id to find the run in the run history.

Without an input override:

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
var payload = new AgentResponsesApiRoutineDispatch
{
    Input = BinaryData.FromObjectAsJson("Run the daily summary for testing."),  // optional
};

RoutineDispatchResult result = await routinesClient.DispatchAsync(
    name: "daily-summary",
    payload: payload);

Console.WriteLine($"dispatch_id: {result.DispatchId}");
Console.WriteLine($"task_id:     {result.TaskId}");

// Invocations API routine
var payload2 = new AgentInvocationsApiRoutineDispatch
{
    Input = BinaryData.FromObjectAsJson("Run the agent for testing."),  // optional
};

RoutineDispatchResult result2 = await routinesClient.DispatchAsync(
    name: "my-invocations-routine",
    payload: payload2);

// Responses API routine
const result = await project.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 project.beta.routines.dispatch("my-invocations-routine", {
  payload: {
    type: "invoke_agent_invocations_api",
    input: "Run the agent for testing.",  // optional
  },
});

Queue a manual run for a Responses API routine:

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

The command prints the dispatch_id and task_id. Use the dispatch_id to find the run in the run history.

View run history

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

  1. Open the routine in Microsoft Foundry.
  2. The table on the routine detail page lists past runs. Each row shows the response ID, when the run triggered, its duration, and its state (for example Completed or Failed).
  3. Use the Last day, 7D, 1M, or Custom range controls above the table to filter the time window.
  4. Select a response ID to open the full run, including the response and any error details.

List all runs for a routine:

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

Example response:

{
  "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}")

await foreach (RoutineRun run in routinesClient.GetRoutineRunsAsync("daily-summary"))
{
    Console.WriteLine($"{run.Id}  phase={run.Phase}  source={run.AttemptSource}  started={run.StartedAt}");
    if (run.Phase == RoutineRunPhase.Failed)
    {
        Console.WriteLine($"  error: {run.ErrorType} — {run.ErrorMessage}");
    }
}

for await (const run of project.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}`);
  }
}

Listing run history through azd ai routine isn't supported in preview. Use the Foundry portal, REST API, or an SDK to retrieve runs.

List and retrieve routines

The Routines page shows all routines in your project. Select any routine to see its configuration and run history.

List all routines in the project:

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

Retrieve a specific routine:

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
await foreach (ProjectsRoutine r in routinesClient.GetRoutinesAsync())
{
    Console.WriteLine($"{r.Name}  enabled={r.IsEnabled}  triggers={string.Join(", ", r.Triggers.Keys)}");
}

// Get a single routine
ProjectsRoutine routine = await routinesClient.GetAsync("daily-summary");
Console.WriteLine(routine);

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

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

Retrieve a single routine:

azd ai routine show once-on-release-day

Listing all routines through azd ai routine isn't supported in preview. Use the Foundry portal, REST API, or an SDK.

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.

  1. Open the routine in Microsoft Foundry.
  2. Select Edit.
  3. Change the trigger or action settings.
  4. Select Save.

Reissue the PUT request with the updated body. Include all fields. Omitted fields reset to defaults.

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}")

var action = new AgentResponsesApiRoutineAction { AgentName = agentName };

var routineOptions = new ProjectsRoutineOptions(
    action: action,
    description: "Updated: runs at 08:00 UTC on weekdays.",
    enabled: true);

routineOptions.Triggers.Add("weekday-morning", new ScheduleRoutineTrigger(
    cronExpression: "0 8 * * 1-5",
    timeZone: "UTC"
));

ProjectsRoutine updated = await routinesClient.CreateOrUpdateAsync(
    name: "daily-summary",
    options: routineOptions);

Console.WriteLine($"Updated at: {updated.UpdatedAt}");

const updated = await project.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}`);

Apply changes from a YAML manifest:

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

The --description flag isn't supported for timer routines in preview. Edit the manifest and reapply it by using --file instead.

Delete a routine

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

  1. Open the routine in Microsoft Foundry.
  2. Select Delete, and then confirm.
curl -sS -X DELETE "$PROJECT_ENDPOINT/routines/daily-summary" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: Routines=V1Preview"

A successful response returns HTTP 204 No Content.

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

await routinesClient.DeleteAsync("daily-summary");
Console.WriteLine("Routine deleted.");

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

azd ai routine delete once-on-release-day

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, "2026-06-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. In the preview, use "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
The routine can't invoke the agent because of its identity configuration. Use an agent that authenticates through its configured identity. Don't use an agent that requires an end-user identity at run time. For an event-based routine, also confirm that the routine creator still has access to the connected resource.
The routine feature isn't available in the project. Confirm that the project is in a supported preview 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

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

  • Last updated on