AutoGineer
Generated banner for Foundry Agentic Loop
Generated logo for Foundry Agentic Loop

Foundry Agentic Loop

GitHubOfficialFirst committed by vieiraaeDistributed by GitHub

  • Skill
  • Workflow
  • Software development
  • MIT
  • Low risk
  • Has scripts
Download ZIP

From the author

Build agentic solutions on Microsoft Foundry, GitHub and Azure: hosted agents, toolbox tools and skills, Foundry IQ grounding and a React/FastAPI app. Three modes: rapid prototyping in an existing Foundry project; spec-driven development (SDD), where the foundry-agentic-loop-workflow runs Specify, Implement, Verify and Deploy to create the Foundry project and deploy with azd, or one phase runs alone; and Improve, which refines this skill and the workflow from past runs. Use for Agentic Loop requests and canvas actions, or end-to-end agent solutions from architecture to Azure deployment. Not for isolated Azure administration or unrelated UI edits.
— the description by vieiraae

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

foundry-agentic-loop provides a structured framework for developing agentic applications. It supports two primary modes: rapid prototyping for existing projects and Spec-Driven Development (SDD) for new projects requiring full Azure deployment pipelines. The skill manages the lifecycle of agents, toolbox tools, Foundry IQ grounding, and web application components, ensuring consistent architecture, security, and observability across the development process.

What it does

  • Orchestrates end-to-end agentic solution development from architecture to Azure deployment.
  • Provides a Spec-Driven Development workflow covering Specify, Implement, Verify, and Deploy phases.
  • Supports rapid prototyping for existing Foundry projects.
  • Manages Foundry hosted agents, toolbox tools, and Foundry IQ grounding configurations.
  • Automates deployment of React/FastAPI applications to Azure Container Apps.
  • Enforces security best practices through managed identities and least-privilege RBAC.

When to use it

  • When building new agentic solutions on Microsoft Foundry that require a structured development lifecycle.
  • When you need to deploy agentic applications to Azure using standardized pipelines.
  • When prototyping agentic features within an existing Foundry project.
  • When you need to integrate Foundry IQ grounding or custom toolbox tools into an agent.

Advantages

  • Ensures architectural consistency through a contract-first development approach.
  • Automates complex deployment tasks using azd and Bicep infrastructure layers.
  • Provides built-in observability via OpenTelemetry and Application Insights integration.
  • Maintains project history and lessons learned to improve future development cycles.
  • Reduces manual configuration errors by enforcing standardized workspace structures.

Usage examples

“Start a new agentic project using the SDD workflow.”
The agent initializes the SDD workflow, creates the necessary project structure, and begins the Specify phase to define the project requirements.
“Deploy my current Foundry project to Azure.”
The agent validates the current configuration, runs the deployment pipeline, and reports the status of the Azure Container Apps deployment.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/github/foundry-agentic-loop/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip foundry-agentic-loop.zip -d .agents/skills

Documentation by vieiraae

Foundry Agentic Loop

Coordinate the solution and use microsoft-foundry for platform operations. Explicit user choices override defaults. Reuse known context, ask only for missing decisions, read only the references a step needs, and report decisions, blockers and endpoints concisely.

Bootstrap (once per session)

  1. Foundry skill. If microsoft-foundry is unavailable, ask, then install it (copilot plugin install azure@awesome-copilot, or gh skill install microsoft/azure-skills microsoft-foundry --agent github-copilot --scope project) and reload skills.

  2. Canvas and workflow. This plugin ships foundry-agentic-loop-canvas and foundry-agentic-loop-workflow, listed as foundry-agentic-loop:<name> or <name>. Call extensions_manage with operation: "list". Never install extensions from a URL and never edit Copilot settings files. If one is listed under neither name, tell the user which is missing and that it ships with the plugin, then ask before running copilot plugin install foundry-agentic-loop@awesome-copilot; after they approve, call extensions_reload once. If one is disabled, tell the user to re-enable it in their extension settings and continue in a new session: running sessions keep it disabled, even after a reload. If one failed, inspect it and report its log. Without the canvas, continue in Chat; without the workflow, SDD cannot start, so offer rapid prototyping.

  3. Canvas. When work starts from Chat, open it once: open_canvas with canvasId: "foundry-agentic-loop-canvas", instanceId: "foundry-agentic-loop" and input: { mode }. Prompts that begin [Agentic Loop canvas action] come from the canvas; follow their target, approval and resume instructions literally.

Choose the mode

SignalMode
Root AGENTS.md has an Agentic Loop sectionIts mode. Switch only when the user confirms, then rewrite the section
Canvas prompt or explicit choiceAs stated
Existing Foundry project selected or named; fast prototype; no deployment pipeline neededRapid prototyping: rapid.md
Spec, new Foundry project, azd or IaC, CI-ready repo or full Azure deploymentSDD: sdd.md
Improve, learn from runs, or the canvas improve promptImprove: improve.md; measure changes with node scripts/evals.mjs (index, then run --base <commit>; exit 2 means evals are unavailable, so stop)
One named SDD phase, with no run activeIts guide (Specify, Implement, Verify or Deploy) with the SDD defaults

Otherwise ask once with the choices "Rapid prototyping (existing Foundry project)" and "SDD (new project, deployed with azd)".

Lock it in. Before any other workspace write (in the rapid preflight, or just before the SDD workflow starts), upsert the section from agents-md-rapid.md or agents-md-sdd.md into the root AGENTS.md: replace everything between its foundry-agentic-loop begin and end markers, or append it, keeping other content; then read it back. The section routes short commands such as deploy and locks the mode for Chat, the canvas and the workflow. Azure settings go only in .azure/deployment-plan.md, never in AGENTS.md. Improve mode never writes it.

Defaults

  • Agents: Foundry hosted agents exposing the Responses API, Python 3.13, code deployment. Create them through microsoft-foundry's foundry-agent/create/quick-start-hosted.md with the Basic sample, resolved through that skill, never a guessed URL. Use its advanced workflow only when quick-start cannot support a capability, keeping these defaults. Prompt agents only when requested.

  • Framework: the Copilot SDK for agents that use runtime skills (recipe, reference agent); Microsoft Agent Framework for basic agents and explicit workflows. If a workflow also needs skills, clarify. One framework per agent.

  • Models: rapid keeps the Basic sample's model deployment, or verifies and reuses a supplied one; SDD defaults to gpt-5.4-mini unless the spec needs otherwise. Run the joint placement preflight in foundry-models.md before creating resources. Never hard-code a replacement or silently duplicate a deployment.

  • Tools and knowledge: one governed Foundry toolbox for built-in tools, MCP connections and agent skills; agents use its endpoint, not hard-coded tool URLs. Private knowledge uses Foundry IQ through the toolbox, with citations for supported claims and a deterministic insufficient-evidence response; test both. Add Search only when needed. Reuse run skills the user names from the run catalog instead of regenerating them.

  • App: React + Vite, FastAPI and FastMCP (streamable HTTP) on Azure Container Apps. Rapid deploys with az containerapp up --name <app> --source <dir> --resource-group <rg> --environment <env>; SDD uses azd with a microsoft.foundry layer plus a Bicep (AVM) app layer, remoteBuild: true and one ACR pulled by managed identity. Add services from the reference architecture only when the solution needs them.

  • App access: decide it from the data. When everything the app shows is sample, synthetic or deliberately public, default to no end-user sign-in, even for staff users; services still authenticate with managed identities and need no anonymous-session or identity-verification workarounds. When it shows private, sensitive or user-specific data, ask for the access model before deploying and default to internal ingress or Entra sign-in; anonymous access needs explicit approval. With sign-in, the API pre-authorizes the SPA, the spec states how automated browser tests get a user token, and Implement proves that token path as soon as the app registrations exist.

  • Identity and safety: managed identities and least-privilege keyless RBAC (contract; preflight with check_rbac_preflight.py). Check management-plane, data-plane and role-assignment rights separately; subscription Owner does not grant Foundry data-plane roles. Plan roles for identities not yet created and verify actual principals after creation. No credentials in browser code or Git; Foundry guardrails on.

  • Observability: OpenTelemetry from the backend, agents, MCP servers and model calls into one Application Insights connected to the project (observability.md). Sensitive content capture stays off unless approved with redaction and retention controls.

Workspace files

FileHolds
AGENTS.md (root)The mode lock and short-command routes; never Azure settings
README.md (rapid) or docs/spec.md (SDD, from the spec template)The contract
.azure/deployment-plan.mdEvery Azure setting, in both modes (template)
.env (Git-ignored)What the canvas reads: FOUNDRY_PROJECT (full ARM ID, once validated or created), LOCAL_FRONTEND and DEPLOYED_FRONTEND (verified URLs only). Upsert, keep other keys and read back
docs/LOOP.mdLessons (template)
.agentic-loop/runs/<runId>.jsonSDD flight records, written by the workflow
.devcontainer/devcontainer.jsonOptional dev container (asset)

Working rules

  • Contract first. Freeze service names, environment variables, protocols, endpoints, schemas, auth, streaming, errors and versions (implementation-contract.md) before parallel work.

  • Integration first. Pass the hosted integration checkpoint with a minimal agent before building full orchestration, UI or backend: always a model request, plus a toolbox skill load and a safe MCP call only when the architecture needs them. Record excluded capabilities as N/A with the reason, never as passed, and never add unused ones to satisfy the checkpoint.

  • Evidence, not signals. HTTP 200, exit 0 or active never pass alone; require terminal completion, schema-valid output, execution evidence and correlated traces. Fix with bounded diagnostics, not unchanged redeployments.

  • Wait by completion. Provisioning, deployments, role-assignment propagation and agent readiness end when their command or status check says so: run the command synchronously with a long initial wait, or poll its status every 30-60 s against a stated deadline. Never chain fixed sleeps; keep coding while Azure works.

  • Subagents. Before the checkpoint, parallelize only research and preflight. After it, give each worker a bounded goal, exclusive workspace-relative files or folders, skill references, verified context, the contract, acceptance checks and stop conditions. One owner (the coordinator, or the SDD phase lead) holds the contract and the shared files: azure.yaml, infra/, docs/, .env, .azure/, .agentic-loop/, AGENTS.md and the root lockfiles. Keep teams small, avoid recursive delegation, serialize shared Azure mutations and integrate centrally; worker success is not acceptance. Delegation grants no extra approval. Without subagents, work sequentially and say so.

  • Safety. Reuse resources; confirm billable, security or compliance changes; delete without approval only a resource this build created whose provisioning failed; never sign in for the user; never report an unverified deployment as successful.

  • Workspace boundary. Builds stay inside the workspace: read lessons only from its own docs/LOOP.md, scaffold from the Foundry samples and these references, and use code from other folders only when the user names them. Only improve mode reads past runs elsewhere.

  • Work IQ context. Only when the user or a canvas prompt asks for it, query the workiq MCP server before clarifying questions, fold in only the requirements that matter, cite each by source type and confirm them. Never copy confidential content, personal data or secrets into the workspace; if Work IQ is unavailable or needs consent, say so and continue without it.

  • Companions and SDKs. Verify installed SDK APIs against the latest stable release (or the newest stable one the build's package index serves, recording the gap) and lock versions before generating code; package sources beat stale guidance. Consult the build catalog only for needed capabilities; respect pins, ask before installs and route third-party skill defects upstream.

Lessons

Right after a fix is verified (the failing probe or an equivalent boundary check reruns successfully; an edit, commit or deployment alone is not resolution), upsert a lesson in the workspace's docs/LOOP.md from the template before unrelated work, then read it back. Keep user notes, update matching lessons instead of duplicating them, and never include secrets, raw .env values or payloads. The coordinator, or the SDD phase lead, owns writes; workers report evidence. Lessons never authorize skill edits or weaker gates; improve mode applies them with approval.

Files

references/azd-layout.md

azd layout for SDD solutions

Reference for the Implement and Deploy phases. All names below are examples. Take the real names from docs/spec.md.

Scaffold into an existing workspace

Specify leaves docs/ and .azure/ in the workspace. azd ai agent init . with --no-prompt declines a non-empty folder ("confirmation declined; app was not initialized"), and adoption rejects --force. Scaffold the first agent in an empty folder instead:

  1. mkdir .scaffold && cd .scaffold, then run azd ai agent init . -e <env> --no-prompt -t <azureYamlUrl> --deploy-mode code --runtime python_3_13 --entry-point main.py --agent-name <agent>, taking the URL from the sample's initCommand (-m is deprecated). Add --model <model> when the spec differs from the sample default.

  2. Move the sample folder (.scaffold/src/<sample>) to src/agents/<agent> and update that service's project: path in azure.yaml.

  3. Move azure.yaml, AGENTS.md and CLAUDE.md to the root only when absent there; otherwise merge them, keeping the root AGENTS.md Agentic Loop section unchanged.

  4. Copy .scaffold/.azure/config.json and .scaffold/.azure/<env>/ into .azure/. Never move or overwrite .azure/: it holds deployment-plan.md.

  5. Init git-stages its files: run git rm --cached -r -q --ignore-unmatch .scaffold, then rm -rf .scaffold, and check that git status --short lists no .scaffold path.

  6. Write .agentignore (not .azdignore) in every agent folder, listing tests, evaluators, eval config, the Dockerfile, virtual environments and .env*, so the code package carries runtime files only.

Add further agents with azd ai agent init --src, as in Implement step 3.

azure.yaml

Keep the ai-project block and the agent settings that the scaffold wrote, then add the extra services and the infra layers.

Declarative skill, connection and toolbox services need these extension versions:

  • azure.ai.agents 1.0.0-beta.17 or later

  • azure.ai.connections and azure.ai.toolboxes 1.0.0-beta.8 or later

  • azure.ai.skills 1.0.0-beta.1 or later

Check the installed versions with azd ext list. Upgrade only with approval, using azd extension update <id>.

requiredVersions:
  azd: '>=1.32.0'
  extensions:
    azure.ai.agents: '>=1.0.0-beta.17'
    azure.ai.connections: '>=1.0.0-beta.8'
    azure.ai.toolboxes: '>=1.0.0-beta.8'
    azure.ai.skills: '>=1.0.0-beta.1'
name: claims-triage
services:
  ai-project:                          # from the scaffold; models live here
    host: azure.ai.project
    deployments: [...]
  claims-policy:                       # Foundry skill: folder with SKILL.md
    host: azure.ai.skill
    uses: [ai-project]
    archive: skills/claims-policy
  claims-mcp:                          # FastMCP on Container Apps
    host: containerapp
    project: src/mcp/claims
    language: python
    docker: { path: Dockerfile, remoteBuild: true }
  claims-mcp-conn:
    host: azure.ai.connection
    uses: [ai-project, claims-mcp]
    category: RemoteTool
    target: ${MCP_CLAIMS_URL}
    authType: AgenticIdentityToken     # see "MCP auth"
    audience: ${MCP_CLAIMS_AUDIENCE}
    env:
      MCP_CLAIMS_URL: ${MCP_CLAIMS_URL}
      MCP_CLAIMS_AUDIENCE: ${MCP_CLAIMS_AUDIENCE}
  claims-tools:                        # writes TOOLBOX_CLAIMS_TOOLS_MCP_ENDPOINT
    host: azure.ai.toolbox
    uses: [ai-project, claims-policy, claims-mcp-conn]
    skills: [{ name: claims-policy }]
    tools:
      - type: mcp
        server_label: claims
        server_url: ${MCP_CLAIMS_URL}
        connection: claims-mcp-conn
        require_approval: never
    env: { MCP_CLAIMS_URL: ${MCP_CLAIMS_URL} }
  triage-agent:
    host: azure.ai.agent
    project: src/agents/triage-agent
    uses: [ai-project, claims-tools]
    # keep kind, name, codeConfiguration, protocols and container from the scaffold
    env:
      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
      MODEL_API_BASE_URL: ${MODEL_API_BASE_URL}   # Copilot SDK agents; set after provision
      TOOLBOX_ENDPOINT: ${TOOLBOX_CLAIMS_TOOLS_MCP_ENDPOINT}
  backend:
    host: containerapp
    project: src/backend
    language: python
    docker: { path: Dockerfile, remoteBuild: true }
  frontend:
    host: containerapp
    project: src/frontend
    language: js
    docker: { path: Dockerfile, remoteBuild: true }
infra:
  layers:
    - name: foundry
      provider: microsoft.foundry
      path: infra/foundry              # README.md only
    - name: app
      provider: bicep
      path: infra/app
      dependsOn: [foundry]
Rules for azure.yaml

  • Platform variables: never set FOUNDRY_* or AGENT_* names in an agent's env, because the platform injects them. Deploy writes AGENT_<SERVICE>_NAME, _VERSION and _<PROTOCOL>_ENDPOINT to the azd environment.

  • Older extensions without upgrade approval: remove the skill, connection and toolbox services. Recreate them in an idempotent postprovision hook that runs these commands in this order:

    1. azd ai skill create|update <name> --file ./skills/<name>

    2. azd ai connection create <name> --kind remote-tool --target <url> --auth-type agentic-identity --audience <aud> --force

    3. azd ai toolbox create <name> --from-file <file>

    See foundry-toolbox.md.

  • MCP auth: the agent identity calls MCP tools through the connection (rbac-contract.md).

    • Keyless (default): use AgenticIdentityToken with the MCP server's Entra app ID URI as the audience. The MCP server validates the token with Container Apps authentication, which must allow the agents' client IDs (grants after deploy). This needs an Entra app registration, which the deployer creates or which comes from the Microsoft Graph Bicep extension; record each one's display name and app ID in docs/implementation.md for teardown. If the tenant blocks app registrations, report the gate as blocked.

    • No auth: use authType: None only for read-only tools over synthetic or public data, with explicit approval. Record it as an assumption in the spec.

infra/app (Bicep with AVM)

main.bicep sets targetScope = 'resourceGroup' and deploys to AZURE_RESOURCE_GROUP. The foundry layer creates rg-<env> first. The microsoft.foundry provider may put the account and project in its own group (AZURE_FOUNDRY_RESOURCE_GROUP, for example rg-<env>-foundry): reference them, and create their role assignments and project connection, in a module with scope: resourceGroup(aiResourceGroupName).

Pin each AVM module to its latest version. Find it at https://mcr.microsoft.com/v2/bicep/avm/res/<path>/tags/list.

Module or resourcePurpose
managed-identity/user-assigned-identityOne identity per app; pass its AZURE_CLIENT_ID to the app
operational-insights/workspace, insights/componentLog Analytics and Application Insights
Microsoft.CognitiveServices/accounts/projects/connections@2025-04-01-previewConnects App Insights to the existing project. Set category: 'AppInsights', target to the component ID, authType: 'ApiKey', isSharedToAll: true, credentials.key to the connection string and metadata: { ApiType: 'Azure', ResourceId: <component ID> }.
container-registry/registryBasic SKU with the admin user disabled; grant AcrPull to every app identity
app/managed-environmentConsumption profile, logs sent to the workspace
app/container-app ×nSee Container app settings
Microsoft.Authorization/roleAssignmentsOne per RBAC contract row, such as backend → Foundry User on the account and apps → Monitoring Metrics Publisher. Reference roles by definition ID.
Container app settings

  • Tag each app with azd-service-name: <service key>.

  • Set the image to empty(<app>Image) ? '<placeholder>' : <app>Image, with <app>Image from ${SERVICE_<NAME>_IMAGE_NAME=} and the first-provision placeholder mcr.microsoft.com/azuredocs/containerapps-helloworld:latest, so a re-provision keeps the deployed image.

  • Pull images through registries with the app's identity.

  • Set targetPort to the app's real port.

  • Keep names to 32 characters or fewer.

Grants after deploy

The hosted agent's runtime identities exist only after deploy. An idempotent postdeploy hook creates their RBAC contract rows and the MCP allow-lists. For each agent:

  1. Run azd ai agent show <agent> --output json --no-prompt and read the principal and client IDs of instance_identity and blueprint.

  2. Grant the runtime rows to the instance principal only; the blueprint returns PrincipalTypeNotSupported. Check with az role assignment list --assignee <id> --role <role> --scope <scope> first, then run az role assignment create --assignee-object-id <id> --assignee-principal-type ServicePrincipal only when missing.

  3. For each keyless MCP app (and any other Easy Auth app the agents call), allow the instance and blueprint client IDs of every agent whose toolbox reaches it: all agents for a shared toolbox. Store the sorted list comma-separated with azd env set, for example MCP_ALLOWED_CLIENT_IDS. Bicep split()s it into validation.defaultAuthorizationPolicy.allowedApplications, so a re-provision keeps it. With an empty list the toolbox's tools/list returns 403.

  4. Patch the live apps: az rest GET https://management.azure.com<appId>/authConfigs/current?api-version=2024-03-01, set allowedApplications, then PUT.

Grants take 2–5 minutes to apply: retry the first hosted invoke with backoff until a fixed deadline instead of redeploying unchanged code. After azd up or azd deploy, confirm with az role assignment list --assignee <principalId> --all and each app's authConfigs/current; if anything is missing, run azd hooks run postdeploy --no-prompt and check again.

Parameters

main.parameters.json maps values from the azd environment, including the foundry layer's outputs:

{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION}" },
    "principalId": { "value": "${AZURE_PRINCIPAL_ID}" },
    "aiAccountName": { "value": "${AZURE_AI_ACCOUNT_NAME}" },
    "aiProjectName": { "value": "${AZURE_AI_PROJECT_NAME}" },
    "aiResourceGroupName": { "value": "${AZURE_FOUNDRY_RESOURCE_GROUP}" },
    "projectEndpoint": { "value": "${FOUNDRY_PROJECT_ENDPOINT}" },
    "mcpAllowedClientIds": { "value": "${MCP_ALLOWED_CLIENT_IDS=}" },
    "backendImage": { "value": "${SERVICE_BACKEND_IMAGE_NAME=}" }
  }
}
Outputs

Each output becomes an azd environment variable:

  • AZURE_CONTAINER_REGISTRY_ENDPOINT (container app deploys need it)

  • APPLICATIONINSIGHTS_CONNECTION_STRING

  • SERVICE_<NAME>_URI for each app

  • MCP_<NAME>_URL, including the MCP route, for example /mcp

App wiring

  • Backend: receives FOUNDRY_PROJECT_ENDPOINT, the agent name and AZURE_CLIENT_ID as environment variables. It calls the agent's dedicated endpoint with a token for https://ai.azure.com/.default, as in the hosted integration checkpoint.

  • Frontend: nginx serves the Vite build and proxies /api to ${BACKEND_URL} through the nginx image's templates/ substitution. This needs no CORS and no build-time URLs.

  • Telemetry: every app receives APPLICATIONINSIGHTS_CONNECTION_STRING (observability.md).

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs Python, Needs Node.js

Security

What our scanner noticed· Low risk

  • Instructions that use the network
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by
GitHub avatar of vieiraaevieiraae
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/foundry-agentic-loop · commit 797337f
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
vieiraae

AutoGineer is not affiliated with or endorsed by vieiraae or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download foundry-agentic-loop.zip