Manage Foundry Routines (azd ai routine)
Create, read, update, and delete Microsoft Foundry routines with the Azure Developer CLI (azd). A routine pairs a trigger (timer, recurring schedule, GitHub issue, or custom external event) with an action that invokes a Foundry agent. Use only the azd path for routine work: imperative azd ai routine commands or declarative host: azure.ai.routine services in azure.yaml.
Preview. Routines ship in the
azure.ai.routinesazd extension. The command surface isazd ai routine <verb>; do not use Foundry MCP tools, REST, or SDK for routine CRUD in this skill.
Quick Reference
| Property | Value |
|---|---|
| Primary CLI | azd ai routine (extension azure.ai.routines) |
| Install extension | azd extension install azure.ai.routines |
| CRUD verbs | create, list, show, update, delete |
| Routine operations | enable, disable, dispatch, run list |
| Declarative form | azure.yaml service with host: azure.ai.routine, upserted by azd deploy / azd up |
| Agent prompt/input | Set action.input in a routine manifest or azure.yaml; use a string for the agent responses protocol and the target payload for the agent invocations protocol. azd ai routine create flags do not include --input |
| Project endpoint | --project-endpoint, then AZURE_AI_PROJECT_ENDPOINT, global azd ai project set, then FOUNDRY_PROJECT_ENDPOINT |
| Output format | --output json or --output table (default) |
When to Use This Skill
- Schedule an agent on a one-shot timer or recurring cron schedule.
- Trigger an agent from a GitHub issue event or custom external event.
- List, inspect, update, enable, disable, dispatch, or delete existing routines.
- Manage routines declaratively in
azure.yamlsoazd up/azd deploykeeps them in sync.
A routine references an agent; it does not create one. Deploy or identify the target agent first (see deploy / create), then attach a routine to it.
Workflow
Step 1 - Verify the environment
Before any routine command, run the shared verification script to confirm azd, az, auth, and the base Foundry extensions are ready:
../create/scripts/verify-environment.sh # macOS / Linux
../create/scripts/verify-environment.ps1 # Windows (pwsh)Act on the summary prefixes:
[OK]- nothing to do.[WARN]- non-blocking; continue.[ACTION]- resolve first, then rerun the script. Never runaz loginorazd auth loginfor the user; stop and ask them to log in manually. Missing base extensions (azure.ai.agents,azure.ai.projects,microsoft.foundry) can be installed withazd extension install <name>.
Do not continue while any [ACTION] remains.
Step 1b - Check the routines extension
The shared script does not check azure.ai.routines. Confirm it is installed:
azd extension list --installed --output jsonIf missing, install it (ask first in interactive mode; install directly in non-interactive mode):
azd extension install azure.ai.routinesVerify the command surface:
azd ai routine --helpIf azd ai routine reports an unknown command after install, the azd core is too old. The extension requires azd >= 1.27.0; upgrade azd (https://aka.ms/azd-install) and retry.
Step 2 - Resolve the Foundry project endpoint
Every routine command targets a Foundry project endpoint. azd ai routine resolves it in this order:
-p/--project-endpoint <url>on the command.- Active azd environment
AZURE_AI_PROJECT_ENDPOINT(azd env get-values). - Global config from
azd ai project set <endpoint>. FOUNDRY_PROJECT_ENDPOINTenvironment variable.- Otherwise the command fails with a missing-endpoint error.
Prefer the azd env inside an azd project. Otherwise set it once:
azd env set AZURE_AI_PROJECT_ENDPOINT "https://<account>.services.ai.azure.com/api/projects/<project>"
# or, outside an azd project:
azd ai project set "https://<account>.services.ai.azure.com/api/projects/<project>"The endpoint host must end with .services.ai.azure.com and use https with no explicit port.
Two Ways to Create a Routine
A routine is the same Foundry resource — keyed by its name — no matter how you create it. Both paths go through azd and act on that same named resource, so a routine created one way can later be managed the other way. Declarative azd deploy always upserts idempotently; imperative azd ai routine create refuses to overwrite an existing routine unless you pass --force. Pick a path, then read its reference doc for exact examples.
Way 1 — Imperative: azd ai routine create
Create the routine directly against the Foundry project with a single command — flags, or a --file manifest when it must carry a stored prompt/payload (action.input; there is no --input flag). Best for one-off scheduling, quick experiments, ad-hoc CRUD, and working outside an azd project — no azure.yaml required. → CLI CRUD and Operations
Way 2 — Declarative: azure.yaml + azd deploy
Declare the routine as a host: azure.ai.routine service in azure.yaml, then let azd deploy / azd up upsert it. Best when the routine should be versioned with the agent in source control and reproduced per azd environment — GitOps, multi-env, CI/CD. → Declarative Routines
Which path?
| Situation | Path |
|---|---|
One-off schedule, quick experiment, or no azure.yaml in play |
Way 1 — imperative |
| Routine versioned with the agent, reproduced per environment, GitOps / CI/CD | Way 2 — declarative |
| Unsure and already in an azd project with the agent | Way 2 — declarative keeps the routine and agent in sync |
Read, update, enable/disable, manually dispatch, inspect past runs, and delete are imperative-only operations that work on a routine regardless of how it was created — see CLI CRUD and Operations.
Error Handling
| Symptom | Cause | Resolution |
|---|---|---|
unknown command "routine" / unknown command "ai" |
Extension not installed or azd too old | azd extension install azure.ai.routines; ensure azd >= 1.27.0 |
| Missing project endpoint error | No endpoint resolved | Set AZURE_AI_PROJECT_ENDPOINT, run azd ai project set <url>, or pass -p <url> |
routine "<name>" already exists on create |
Name collision | Re-run with --force to upsert, or choose a different name |
--trigger cannot be changed on an existing routine (same for --action) |
Trigger/action type is immutable | Delete then create with the new type |
--force is required when --no-prompt is set on delete |
Non-interactive delete without confirmation | Add --force |
routine "<name>" not found |
Wrong name or wrong project | Check the name and resolved endpoint with show / list |
host "..." is not a recognized Foundry host |
Endpoint host invalid | Use https://<account>.services.ai.azure.com/api/projects/<project> (no port) |
json: cannot unmarshal number into Go struct field Routine.created_at of type string |
The routines extension could not decode a routine response after the service call | Do not assume the operation failed. Check with show <name> and list; if both decode badly, the routine may exist but cannot be decoded by the current extension. |
Network isolation / PublicNetworkAccessDisabled / 403 |
Project has public access disabled | See Network Isolation Errors |
Additional Resources
- CLI CRUD and Operations
- Declarative Routines
- azd ai CLI Reference
- Deploy a Foundry Agent - deploy the agent a routine will invoke
- Invoke a Foundry Agent - smoke-test the agent before scheduling it
- Microsoft Foundry Skill (index)