AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--microsoft-foundry at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 151

foundry-agent/routine/routine.md

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.routines azd extension. The command surface is azd 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.yaml so azd up / azd deploy keeps 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 run az login or azd auth login for the user; stop and ask them to log in manually. Missing base extensions (azure.ai.agents, azure.ai.projects, microsoft.foundry) can be installed with azd 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 json

If missing, install it (ask first in interactive mode; install directly in non-interactive mode):

azd extension install azure.ai.routines

Verify the command surface:

azd ai routine --help

If 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:

  1. -p / --project-endpoint <url> on the command.
  2. Active azd environment AZURE_AI_PROJECT_ENDPOINT (azd env get-values).
  3. Global config from azd ai project set <endpoint>.
  4. FOUNDRY_PROJECT_ENDPOINT environment variable.
  5. 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