AGENTIC MEMORY

Skills

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

← Back to Skills

foundry-agentic-loop

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.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

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 github--foundry-agentic-loop at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, 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 · 41

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 resource | Purpose | | --- | --- | | managed-identity/user-assigned-identity | One identity per app; pass its AZURE_CLIENT_ID to the app | | operational-insights/workspace, insights/component | Log Analytics and Application Insights | | Microsoft.CognitiveServices/accounts/projects/connections@2025-04-01-preview | Connects 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/registry | Basic SKU with the admin user disabled; grant AcrPull to every app identity | | app/managed-environment | Consumption profile, logs sent to the workspace | | app/container-app ×n | See Container app settings | | Microsoft.Authorization/roleAssignments | One 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).