microsoft-foundry

name	microsoft-foundry
description	Expert knowledge for Microsoft Foundry (aka Azure AI Foundry) development including troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. Use when building Foundry agents with IQ retrieval, Azure OpenAI, VNet/private connectivity, CI/CD, or Copilot/Teams publishing, and other Microsoft Foundry related development tasks. Not for Content Safety in Foundry Control Plane (use azure-content-safety), Azure Content Understanding in Foundry Tools (use azure-content-understanding), Azure Speech in Foundry Tools (use azure-speech), Microsoft Foundry Classic (use microsoft-foundry-classic).
compatibility	Requires network access. Uses mcp_microsoftdocs:microsoft_docs_fetch or fetch_webpage to retrieve documentation.
metadata	{"generated_at":"2026-08-09","generator":"docs2skills/1.0.0"}

Microsoft Foundry Skill

This skill provides expert guidance for Microsoft Foundry. Covers troubleshooting, best practices, decision making, architecture & design patterns, limits & quotas, security, configuration, integrations & coding patterns, and deployment. It combines local quick-reference content with remote documentation fetching capabilities.

How to Use This Skill

IMPORTANT for Agent: Use the Category Index below to locate relevant sections. For categories with line ranges (e.g., L35-L120), use read_file with the specified lines. For categories with file links (e.g., [security.md](security.md)), use read_file on the linked reference file

IMPORTANT for Agent: If metadata.generated_at is more than 3 months old, suggest the user pull the latest version from the repository. If mcp_microsoftdocs tools are not available, suggest the user install it: Installation Guide

This skill requires network access to fetch documentation content:

• Preferred: Use mcp_microsoftdocs:microsoft_docs_fetch with query string from=learn-agent-skill. Returns Markdown.
• Fallback: Use fetch_webpage with query string from=learn-agent-skill&accept=text/markdown. Returns Markdown.

Category Index

Category	Lines	Description
Troubleshooting	L37-L46	Diagnosing and fixing hosted agent, evaluation/observability, webhook, and service issues, including health checks, recovery from data loss, and known bugs/workarounds.
Best Practices	L47-L61	Best practices for configuring and tuning Foundry agents: tools, routing, system messages, safety, evaluation, latency/throughput, and operating provisioned deployments.
Decision Making	L62-L105	Guides for choosing models, deployments, hosting, networking, billing modes, and upgrade/migration paths (Assistants→Foundry, preview→GA, Azure OpenAI→Foundry), plus cost/perf optimization and DR.
Architecture & Design Patterns	L106-L113	Design patterns for secure, scalable Foundry agents: VNet networking, private retrieval with Foundry IQ, shared session pooling, and high availability architectures.
Limits & Quotas	L114-L133	Quotas, rate limits, regions, and throughput settings for agents, models (Claude, Azure OpenAI, partner), vector stores, sessions, AI Gateway, and evaluation, including gov/enterprise options.
Security	L134-L181	Identity, RBAC, networking, guardrails, data privacy, compliance, and policy controls for securing Foundry agents, models, tools, traces, and infrastructure.
Configuration	L182-L250	Configuring and operating Foundry agents and models: YAML schemas, runtime contracts, networking, storage, observability, evaluations, OpenTelemetry, Azure OpenAI, and private/managed connectivity.
Integrations & Coding Patterns	L251-L341	Patterns and code to integrate Foundry agents and models with tools, data, MCP, Azure/OpenAI APIs, tracing, memory, voice, search, and external services for end-to-end agent solutions.
Deployment	L342-L367	Deploying and managing Foundry hosted agents and models: infrastructure setup, CI/CD, private registries, publishing to Copilot/Teams, evaluations, red teaming, and healthcare/model-specific deployments.

Troubleshooting

Topic	URL
Check hosted agent project health with agent doctor	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/agent-doctor
Troubleshoot Microsoft Foundry hosted agent issues	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/debug-hosted-agent
Recover Foundry Agent Service from resource and data loss	https://learn.microsoft.com/en-us/azure/foundry/how-to/agent-service-operator-disaster-recovery
Troubleshoot Foundry evaluation and observability issues	https://learn.microsoft.com/en-us/azure/foundry/observability/how-to/troubleshooting
Set up and troubleshoot Azure OpenAI webhooks	https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/webhooks
Known issues and workarounds for Microsoft Foundry services	https://learn.microsoft.com/en-us/azure/foundry/reference/foundry-known-issues

Best Practices

Topic	URL
Apply tool usage best practices in Foundry agents	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/tool-best-practice
Optimize hosted agent instructions, tools, skills, and models	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/optimize-agent-targets
Optimize toolbox tool search to reduce context costs	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/tool-search
Use Task Adherence signals for Foundry agents	https://learn.microsoft.com/en-us/azure/foundry/guardrails/task-adherence
Evaluate Microsoft Foundry AI agents with built-in evaluators	https://learn.microsoft.com/en-us/azure/foundry/observability/how-to/evaluate-agent
Design effective system messages for Azure OpenAI	https://learn.microsoft.com/en-us/azure/foundry/openai/concepts/advanced-prompt-engineering
Apply routing modes and best practices for model router	https://learn.microsoft.com/en-us/azure/foundry/openai/concepts/model-router-how-it-works
Apply safety system message templates in Foundry	https://learn.microsoft.com/en-us/azure/foundry/openai/concepts/safety-system-message-templates
Apply best practices for vision fine-tuning	https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/fine-tuning-vision
Optimize Azure OpenAI latency and throughput in Foundry	https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/latency
Operate provisioned throughput deployments in production	https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/provisioned-get-started

Decision Making

Topic	URL
Check Foundry Agent Service feature availability in Azure Government	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/azure-government
Choose networking options for Foundry Agent Service	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/networking-options
Plan migration from Assistants API to Foundry Agent Service	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/migrate
Decide and migrate to new Foundry agent model	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/migrate-agent-applications
Migrate Foundry hosted agents from preview to latest backend	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/migrate-hosted-agent-preview
Choose the right web grounding tool for Foundry agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/web-overview
Choose the right Microsoft Foundry build approach	https://learn.microsoft.com/en-us/azure/foundry/concepts/choose-build-approach
Decide when and how to adopt Microsoft Foundry GA	https://learn.microsoft.com/en-us/azure/foundry/concepts/general-availability
Plan and manage Microsoft Foundry cost usage	https://learn.microsoft.com/en-us/azure/foundry/concepts/manage-costs
Optimize Foundry model cost and performance	https://learn.microsoft.com/en-us/azure/foundry/control-plane/how-to-optimize-cost-performance
Understand Claude CCU billing and migration in Foundry	https://learn.microsoft.com/en-us/azure/foundry/foundry-models/concepts/claude-models-billing

Architecture & Design Patterns

Topic	URL
Design networking for Foundry Agent Service with BYO VNet	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/agents-networking-deep-dive
Design private agentic retrieval architecture with Foundry IQ	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/foundry-iq-tutorial-private-overview
Pool multiple users onto shared Foundry agent sessions	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/multiplex-session-users
Design high availability for Microsoft Foundry agents	https://learn.microsoft.com/en-us/azure/foundry/how-to/high-availability-resiliency

Limits & Quotas

Topic	URL
Quotas, limits, and regions for Foundry Agent Service	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/limits-quotas-regions
Manage vector store limits and file search behavior	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/vector-stores
Create and manage Foundry hosted agent sessions	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/manage-hosted-sessions
Evaluation rate limits, regions, and enterprise options in Foundry	https://learn.microsoft.com/en-us/azure/foundry/concepts/evaluation-regions-limits-virtual-network
Set AI Gateway token limits and quotas in Foundry	https://learn.microsoft.com/en-us/azure/foundry/configuration/enable-ai-api-management-gateway-portal
Configure token rate limits and quotas in Foundry Control Plane	https://learn.microsoft.com/en-us/azure/foundry/control-plane/how-to-enforce-limits-models
Compare Claude models, quotas, and regions	https://learn.microsoft.com/en-us/azure/foundry/foundry-models/concepts/claude-models
Use partner and community models in Foundry catalog	https://learn.microsoft.com/en-us/azure/foundry/foundry-models/concepts/models-from-partners
Reference quotas and limits for Foundry Models	https://learn.microsoft.com/en-us/azure/foundry/foundry-models/quotas-limits
Manage Foundry model deployment quotas and TPM limits	https://learn.microsoft.com/en-us/azure/foundry/how-to/quota
Manage provisioned throughput quotas for Foundry models

Security

Topic	URL
Configure Agent 365 identity and governance for Foundry agents	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/agent-365-integration
Configure and govern agent identities in Microsoft Foundry	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/agent-identity
Configure authentication for Agent2Agent tools	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/agent-to-agent-authentication
Reference permissions for Foundry hosted agents	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/hosted-agent-permissions
Configure RBAC roles and environment for Foundry Agent Service	https://learn.microsoft.com/en-us/azure/foundry/agents/environment-setup
Understand Foundry Agent Service data and access	https://learn.microsoft.com/en-us/azure/foundry/agents/faq
Attach RAI guardrail policies to Foundry hosted agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/add-hosted-agent-guardrails
Publish and secure Microsoft Foundry agent applications	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/agent-applications
Configure and share Microsoft Foundry agent endpoints	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/configure-agent
Configure Agent 365 data collection for Foundry	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/configure-agent-365-data-collection
Assign Agent 365 observability app role in Entra	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/grant-agent-365-permissions

Configuration

Topic	URL
Define Foundry hosted agents with agent.yaml schema	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/agent-yaml-reference
Use azure.yaml to configure hosted Foundry agents	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/azure-yaml-reference
Configure and troubleshoot Foundry capability hosts for data routing	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/capability-hosts
Implement the Foundry hosted agent runtime contract	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/hosted-agent-contract
Inspect local hosted agents with Agent Inspector	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/agent-inspector
Configure BYOM models with Foundry Agent Service	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/ai-gateway
Author azure.yaml configuration for Foundry hosted agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/author-azure-yaml
Configure Foundry project context for azd AI commands	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/cli-project-context
Configure environment variables for Foundry hosted agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/configure-hosted-agent-env-variables
Configure OpenTelemetry export for Foundry hosted agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/configure-hosted-agent-telemetry
Configure Connected Foundry Models in Agent Service

Integrations & Coding Patterns

Topic	URL
Add Responses or Invocations protocol adapters to hosted agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/add-protocol-adapter
Build real-time voice agents using Foundry WebSockets	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/build-voice-agent
Connect Foundry agents to Foundry IQ knowledge bases	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/foundry-iq-connect
Validate private agentic retrieval with Foundry IQ	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/foundry-iq-tutorial-private-retrieval
Invoke Foundry hosted agents using azd commands	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/invoke-hosted-agent
Enable agent optimizer integration for hosted agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/make-agent-optimizer-ready
Connect Foundry agents to remote A2A endpoints	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/agent-to-agent
Integrate Azure AI Search indexes with Foundry agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/ai-search
Integrate Azure Speech MCP tool with Foundry agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/azure-ai-speech
Integrate Azure Functions as tools for agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/azure-functions
Use Bing grounding tools with Foundry agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/bing-tools

Deployment

Topic	URL
Scaffold and customize hosted agent infrastructure with azd Bicep	https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/cli-infrastructure
Deploy Foundry hosted agents via azd, SDK, or REST	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent
Deploy Foundry hosted agents with private Azure Container Registry	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent-private-azure-container-registry
Initialize Foundry hosted agent projects with azd	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/init-agent-project
Manage lifecycle and versions of Foundry hosted agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/manage-hosted-agent
Publish Foundry agents to Microsoft 365 Copilot and Teams	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/publish-copilot
Publish private-network Foundry agents to Microsoft 365 and Teams via REST	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/publish-copilot-virtual-network
Configure CI/CD pipelines for Foundry hosted agents	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/set-up-ci-cd-cli
Deploy custom code interpreter with Dynamic Sessions	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/custom-code-interpreter
Update Foundry hosted agent endpoints and cards with azd	https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/update-agent-endpoint-cli