microsoft-foundry

Overview

What is the microsoft-foundry skill?

The microsoft-foundry skill is a curated set of workflows and reference docs that guide you through the end-to-end lifecycle of Azure AI Foundry agents. It focuses on practical deployment and operations:

• Creating prompt and hosted agents
• Building Docker images and pushing to Azure Container Registry (ACR)
• Deploying agents to Azure AI Foundry
• Setting up projects, RBAC, quota, and connections
• Running evaluation datasets and managing agent-metadata.yaml
• Configuring standard and private-network agent setups
• Enabling observability, tracing, and troubleshooting

All content comes from the microsoft/azure-skills repository and is structured so you can operationalize agents on Azure AI Foundry without reverse‑engineering the repo layout.

Who is this skill for?

Use microsoft-foundry if you are:

• A backend or platform engineer responsible for deploying and operating Azure AI Foundry agents
• An AI/ML engineer moving prototypes into a production Foundry project
• A developer integrating Foundry agents with existing services, SDKs, or MCP tools
• A technical owner who must reason about RBAC, quota, private networking, and environment setup

If you only need basic Azure infrastructure deployment (App Service, Functions, generic web apps), this skill is not the right fit—use a more general Azure deployment skill instead.

What problems does microsoft-foundry solve?

The skill is designed to solve these recurring challenges:

• "How do I structure my agent repo for Foundry?"
  Use the references/agent-metadata-contract.md guidance for .foundry/ layout and agent-metadata.yaml fields.

• "How do I create and deploy agents consistently?"
  Use the foundry-agent/create and foundry-agent/deploy workflows to create prompt/hosted agents, build containers, push to ACR, and start agent containers.

• "How do I configure projects, connections, RBAC, and quota?"
  Follow project/create, rbac/rbac.md, and quota/quota.md to set up projects, assign roles, and plan capacity.

• "How do I evaluate and observe my agents?"
  Use foundry-agent/eval-datasets, foundry-agent/observe, and foundry-agent/trace to run batch evals, manage datasets and evaluators, and connect to observability resources.

• "How do I handle standard vs private-network setups?"
  Use references/standard-agent-setup.md and references/private-network-standard-agent-setup.md to choose and configure the right networking model.

When is microsoft-foundry a good fit?

Use this skill when you need to:

• Deploy prompt or hosted agents to Azure AI Foundry
• Standardize agent project structure with .foundry/agent-metadata.yaml
• Integrate MCP tools and Azure SDKs into a repeatable workflow
• Manage RBAC, quota, and capacity planning for agent workloads
• Run evaluation datasets and track results across environments
• Set up observability using Application Insights and traces
• Deploy into standard or private-network (VNet) configurations

Do not use this skill when you only need:

• Generic Azure app deployment (web apps, Functions, App Service)
• High-level Azure account or subscription preparation

In those cases, pair this skill with more general Azure deployment/preparation skills or use a dedicated skill like azure-deploy / azure-prepare.

How to Use

Installation

To add microsoft-foundry from the microsoft/azure-skills repository, install it with:

npx skills add https://github.com/microsoft/azure-skills --skill microsoft-foundry

This makes the microsoft-foundry workflows and reference content available to your agent or tooling environment. After installation, the primary entrypoint is SKILL.md in the skills/microsoft-foundry folder.

Repository layout and key folders

After installing the skill or opening it in the repository, you will see the following structure:

• SKILL.md – top-level skill index and sub-skill list
• foundry-agent/ – end-to-end workflows for individual agents
  • create/ – create prompt or hosted agents
  • deploy/ – build and deploy agents, including containers and ACR
  • eval-datasets/ – manage eval datasets and evaluation runs
  • invoke/ – invoke existing agents
  • observe/ – observability setup and monitoring workflows
  • trace/ – trace collection and dataset creation from traces
  • troubleshoot/ – troubleshooting guidance for failed runs
• project/
  • create/ – create and configure Azure AI Foundry projects
  • connections.md – guidance for project-level connections
• rbac/
  • rbac.md – RBAC roles, permissions, and common patterns
• quota/
  • quota.md – quota and capacity planning guidance
  • references/ – capacity planning, error resolution, optimization
• references/
  • agent-metadata-contract.md – .foundry/ layout and agent-metadata.yaml
  • auth-best-practices.md – Azure authentication patterns and RBAC
  • standard-agent-setup.md – standard (non-isolated) agent setup
  • private-network-standard-agent-setup.md – VNet/private-link setup
  • sdk/ – SDK-operations references for when MCP tools are not available

Start with SKILL.md to understand the sub-skills, then drill into the specific scenario folder.

Quick-start workflow: from project to deployed agent

This section outlines a practical path using the microsoft-foundry skill content.

1. Create or prepare your Foundry project

1. Open project/create/create-foundry-project.md.
2. Follow the steps to:
   • Create an Azure AI Foundry project
   • Confirm the project endpoint (for example, https://<resource>.services.ai.azure.com/api/projects/<project>)
   • Link required connections (Cosmos DB, Storage, Azure AI Search, etc.) as required for standard setup
3. Review project/connections.md to ensure your thread storage, file storage, and vector store connections are correctly configured, especially if you plan to use standard agent setup.

2. Configure RBAC and authentication

1. Read rbac/rbac.md to verify:
   • Which roles are needed (Owner, Contributor, User Access Administrator, etc.) on the resource group and Foundry resources
   • How to assign roles following Azure RBAC best practices
2. Open references/auth-best-practices.md and apply its recommendations:
   • Use managed identities and Azure RBAC in production
   • Restrict DefaultAzureCredential to local development
   • Choose the right credential type for production, CI/CD, and dev environments

This ensures your deployments and agent operations can authenticate reliably without hard‑coded secrets.

3. Decide on basic vs standard vs private-network setup

1. Open references/standard-agent-setup.md to understand:
   • Differences between Basic and Standard setups
   • Required connections for standard setup: Cosmos DB, Azure Storage, Azure AI Search, and optionally Azure AI Services
   • Prerequisites such as RBAC roles on the resource group
2. If you need full network isolation, read references/private-network-standard-agent-setup.md:
   • VNet and subnet requirements (agent subnet and private endpoint subnet)
   • Region alignment between Foundry resources and the VNet
   • Use of the official Bicep template for private-network standard agent setup

Choose the setup that matches your compliance and networking requirements before moving on to agent creation.

4. Standardize your agent project layout

1. Open references/agent-metadata-contract.md and align your project with the documented layout:

   <agent-root>/
     .foundry/
       agent-metadata.yaml
       datasets/
       evaluators/
       results/
   

2. Ensure agent-metadata.yaml contains environment definitions with fields such as:

   • defaultEnvironment
   • environments.<name>.projectEndpoint
   • environments.<name>.agentName
   • environments.<name>.azureContainerRegistry (for hosted agents)
   • environments.<name>.observability.* (for Application Insights)
   • environments.<name>.testCases[] for evaluation bundles

This file becomes the source of truth for environment-specific configuration, and the rest of the microsoft-foundry workflows assume it is present and accurate.

5. Create a prompt or hosted agent

1. For prompt agents, open foundry-agent/create/create-prompt.md:

   • Understand the difference between prompt agents and workflows
   • Follow the steps to resolve the project context (endpoint, credentials)
   • Use MCP tools where available and fall back to the azure-ai-projects SDK as documented
   • Provide agent name, model deployment, and instructions, plus optional tools (file search, code interpreter, etc.)

2. For hosted agents, open foundry-agent/create/create.md:

   • Choose whether you are creating a new agent (greenfield) or converting an existing project (brownfield)
   • Select a framework and language based on the sample paths provided (Python or C# frameworks such as the Microsoft Agent Framework or LangGraph)
   • Use the guidance to integrate with the foundry-samples repository where needed

At the end of this step, you should have a Foundry-compatible agent project ready for deployment.

6. Build and deploy the agent

1. Open foundry-agent/deploy/deploy.md.
2. Follow the workflow that covers:
   • Project scan and environment variable collection
   • Dockerfile generation and docker / az acr usage for hosted agents
   • Using MCP tools such as agent_update, agent_container_control, and agent_container_status_get
   • Creating or updating the deployment and starting/stopping agent containers
3. Do not run azd up, azd deploy, az acr build, or docker build in isolation without reviewing this guide—the skill coordinates these commands as part of a complete deployment pipeline.

Once this step is complete, your agent should be deployed and reachable via Azure AI Foundry.

7. Invoke and test the agent

1. Open foundry-agent/invoke/invoke.md.
2. Use the documented patterns to:
   • Resolve the correct environment and endpoint from agent-metadata.yaml
   • Invoke the agent with sample or custom payloads
   • Verify that responses, tools, and state behave as expected

This is a good stage to perform smoke tests before running full evaluation suites.

8. Evaluate and iterate

1. Open foundry-agent/eval-datasets/eval-datasets.md.
2. Use the guidance to:
   • Manage datasets and evaluators under .foundry/datasets and .foundry/evaluators
   • Run evaluation workflows using the testCases definitions from agent-metadata.yaml
   • Store outputs under .foundry/results and compare results by environment or agent version
3. Iterate on your prompts or instructions and re-run evaluations to track improvements over time.

Observability, tracing, and troubleshooting

Observability and monitoring

1. Open foundry-agent/observe/observe.md.
2. Configure observability based on the guidance:
   • Attach Application Insights using the resource ID and connection string fields described in agent-metadata-contract.md
   • Use the recommended dashboards or queries to monitor latency, errors, and throughput

This allows you to monitor production behavior and correlate it with deployment changes.

Tracing and dataset creation from traces

1. Open foundry-agent/trace/trace.md.
2. Use the documented workflows to:
   • Collect traces from your agents
   • Curate datasets from traces and store them under .foundry/datasets
   • Feed these datasets into the evaluation workflows for more realistic testing

This is particularly helpful when you want to turn real user traffic into evaluation scenarios.

Troubleshooting deployments and runtime issues

1. Open foundry-agent/troubleshoot/troubleshoot.md.
2. Follow the troubleshooting guides for issues such as:
   • Deployment failures and container startup errors
   • Misconfigured endpoints, credentials, or connections
   • Quota or capacity errors (cross-reference quota/quota.md and quota/references/*.md)

Use this in combination with logs and Application Insights telemetry to diagnose and resolve problems.

Quota, capacity, and optimization

1. Open quota/quota.md for an overview of:
   • How quota is applied to models and deployments in Azure AI Foundry
   • How to reason about capacity across environments and regions
2. Review the files in quota/references/:
   • capacity-planning.md – helps you estimate capacity for agents based on usage
   • error-resolution.md – maps common quota-related errors to recommended fixes
   • optimization.md – suggests ways to tune workloads to fit within quota limits

This content helps you avoid surprises at scale and keep agents responsive.

FAQ

Is microsoft-foundry required to use Azure AI Foundry?

No. You can use Azure AI Foundry directly via the Azure portal, CLI, or SDKs. The microsoft-foundry skill is a structured guide that packages best practices, workflows, and references in one place so you can set up projects, agents, and environments more consistently.

Can I use microsoft-foundry for non-Foundry Azure services?

Use this skill when your primary goal is deploying and operating Azure AI Foundry agents and projects. For general-purpose deployment of web apps, APIs, or other PaaS services (App Service, Functions, generic containers), use a dedicated Azure deployment skill or guidance instead.

Does microsoft-foundry support both prompt and hosted agents?

Yes. The skill has dedicated content for both:

• foundry-agent/create/create-prompt.md covers prompt agents.
• foundry-agent/create/create.md and foundry-agent/deploy/deploy.md cover hosted agents, including containerization, ACR, and container lifecycle management.

How does microsoft-foundry handle authentication and security?

Security and authentication are covered in references/auth-best-practices.md and rbac/rbac.md:

• Use managed identities and Azure RBAC in production
• Reserve DefaultAzureCredential for local development
• Choose appropriate credentials for CI/CD and on-prem environments

Follow those docs before wiring up SDKs or MCP tools to avoid insecure or brittle setups.

Do I have to use MCP tools, or can I rely on SDKs only?

The content is written to work with MCP tools when available, but also documents SDK-based fallbacks in the references/sdk folder. For example, create-prompt.md explains how to default to the azure-ai-projects SDK when MCP tools are not present.

How do I know if my agent project is structured correctly?

Check your project against references/agent-metadata-contract.md. Ensure you have:

• A .foundry/ directory at the agent root
• A valid agent-metadata.yaml including environments and test cases
• datasets/, evaluators/, and results/ folders as described

If you follow that contract, the rest of the microsoft-foundry workflows will align with your project layout.

Can I use microsoft-foundry with private network (VNet) setups?

Yes. references/private-network-standard-agent-setup.md provides detailed guidance on:

• Required VNet and subnet configuration
• Regional constraints between Foundry resources and the VNet
• Use of the official private-network standard agent setup Bicep template

Use that document alongside references/standard-agent-setup.md when you must keep traffic on a private network.

Where should I start in the repository after installation?

After installing the skill, start with:

1. SKILL.md – for a high-level overview of all sub-skills
2. project/create/create-foundry-project.md – to set up your Foundry project
3. references/agent-metadata-contract.md – to standardize agent layout
4. foundry-agent/create/ and foundry-agent/deploy/ – to build and deploy your first agent

You can then move on to eval-datasets, observe, trace, rbac, and quota as your scenario requires.