version: 1.3.0 scope: Repository review rules, not certification controls. rules: - id: TOOL-001 title: Configure and access MCP through Foundry Toolbox level: recommendation rationale: Foundry Toolbox centralizes MCP configuration, authentication, credential handling, and policy enforcement while allowing tools to be updated without changing hosted-agent code. guidance: - title: "Agent Framework Foundry Toolbox sample" link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox" - title: "LangGraph Foundry Toolbox sample" link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox" when: Apply when the hosted agent uses an MCP server; otherwise skip. checks: >- Inspect deployed code and configuration to determine whether every MCP connection uses Foundry Toolbox instead of the original MCP server. Evidence can include a local azure.ai.toolbox service, a Foundry Toolbox URL such as /toolboxes/{name}/mcp or /toolboxes/{name}/versions/{version}/mcp, a TOOLBOX-named environment variable connected to the MCP path, or a supported Toolbox SDK or constructor. These examples are not exhaustive; accept any clear repository evidence of Toolbox use. statusCriteria: pass: Every deployed MCP connection clearly uses Foundry Toolbox. fail: A deployed MCP connection clearly accesses an original MCP server directly or configures it outside Toolbox. inconclusive: MCP use is evident, but repository evidence cannot determine whether every connection uses Toolbox. - id: AIGW-001 title: Use AI Gateway for required rate limits level: recommendation rationale: Azure API Management AI Gateway can enforce model token or request limits and tool-call limits before traffic reaches backends. guidance: - title: "APIM hosted-agent solution template" link: "https://github.com/microsoft/Foundry-Agent-Solution-Templates/tree/main/apim-hosted-agent" when: Apply when repository requirements or configuration specify a model token or request limit or a tool-call rate limit; otherwise skip. checks: >- 1) Establish a model token, model request, or tool-call rate-limit requirement from repository requirements, configuration, or infrastructure; do not infer one from generic retry or 429 handling. 2) For each affected model or tool call path, trace its runtime endpoint through code, configuration, environment variables, and fallbacks. 3) Verify the endpoint belongs to Azure API Management through an azure-api.net hostname, a linked APIM resource, or infrastructure that maps its custom domain to APIM. Local APIM rate-limit policies are supporting evidence, not required evidence, because policies may be managed externally. statusCriteria: pass: Every required rate-limited path is resolved and uses an APIM AI Gateway endpoint. fail: A fully resolved path with a rate-limit requirement calls its model or tool backend directly. inconclusive: A rate-limit requirement exists, but the call endpoint or its APIM identity cannot be resolved. - id: OBS-001 title: Enable supported tracing for hosted agents level: recommendation rationale: >- Tracing connects agent, model and tool operations to an inspectable telemetry destination. guidance: - title: "Configure hosted-agent telemetry" link: "https://learn.microsoft.com/azure/foundry/agents/how-to/configure-hosted-agent-telemetry" - title: "Set up tracing for agents" link: "https://learn.microsoft.com/azure/foundry/observability/how-to/trace-agent-setup" when: Apply to every hosted agent configured with host azure.ai.agent. checks: >- Read selected service telemetry settings and linked project monitoring. Look for APPLICATIONINSIGHTS_CONNECTION_STRING, OTEL_EXPORTER_OTLP_ENDPOINT or signal-specific OTLP endpoints and their hosting/instrumentation consumer. Inspect matching blocks and directly referenced initialization only. Accept supported automatic hosting or project tracing; do not require explicit instrumentation. An unused setting or library alone is insufficient. If export configuration is external or absent here, stop with inconclusive. statusCriteria: pass: A supported tracing path and its export destination are established without contradictory settings. fail: Active configuration explicitly disables all applicable tracing/export or contradicts its claimed tracing setup. inconclusive: The supported tracing path or export destination cannot be established locally. - id: SDK-001 title: Use consistent Microsoft Agent Framework dependencies level: recommendation rationale: >- Consistent Agent Framework declarations and imports prevent avoidable dependency mismatches; other supported frameworks remain valid. guidance: - title: "Microsoft Agent Framework SDK overview" link: "https://learn.microsoft.com/azure/foundry/how-to/develop/sdk-overview#agent-framework" - title: "Choose a hosted-agent framework" link: "https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-deploy-own-code#choose-your-framework" when: Apply only when the hosted agent declares or imports Microsoft Agent Framework; otherwise skip this rule. checks: >- Read Agent Framework entries in the selected service's dependency manifests, matching lock/central version declarations and entry-point imports. Exact direct pins establish versions without a lock file. Compare the same package across files, not version numbers of different packages. Record literal package/version evidence. Follow direct local version references only; stop on unresolved ranges or generated declarations. Do not inspect installed packages, whole lock files or SDK internals, require latest versions, or infer API compatibility. statusCriteria: pass: Official package-family declarations have determinable direct versions and consistent imports. fail: An unrelated package is presented as Agent Framework, the same dependency has conflicting effective versions, or source imports contradict the declared family. inconclusive: Version resolution or import-to-package mapping remains unresolved. - id: SDK-002 title: Use recommended Foundry hosted-agent SDKs level: recommendation rationale: Approved Foundry hosting packages reduce custom protocol code. guidance: - title: "Python hosted-agent framework samples" link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents" - title: ".NET hosted-agent framework samples" link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/hosted-agents" - title: "Python LangGraph hosting samples" link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/langgraph" when: Apply to every hosted agent configured with host azure.ai.agent. checks: >- Inspect deployed dependency manifests and lock files only. Require at least one approved hosting dependency: Python agent-framework-foundry-hosting, langchain-azure-ai[hosting] (or resolved lock equivalent), or azure-ai-agentserver-invocations; C# Microsoft.Agents.AI.Foundry.Hosting or Azure.AI.AgentServer.Invocations. Generic web framework dependencies alone do not qualify. Do not inspect source code or protocol wiring. statusCriteria: pass: An approved hosting dependency is resolved and no unapproved agent or hosting SDK is declared. fail: No approved hosting dependency is declared, or dependencies include Python openai-agents or another unapproved agent or hosting SDK. inconclusive: Dependency files cannot be resolved enough to classify. - id: AGT-001 title: Do not instruct agents to bypass controls or fabricate success level: warning rationale: Operative agent instructions must not authorize fabricated outcomes, unrestricted consequential actions, or bypasses of runtime controls and required approvals. guidance: - title: "Tool best practices for agents" link: "https://learn.microsoft.com/azure/foundry/agents/concepts/tool-best-practice" - title: "Responsible AI transparency note for agents" link: "https://learn.microsoft.com/azure/foundry/responsible-ai/agents/transparency-note" when: Apply when the repository stores or references instructions that govern the hosted agent at runtime; otherwise skip this rule. checks: >- Read instructions/system-prompt arguments from the selected entry point or configuration and directly referenced local prompt definitions. Locate named symbols rather than reading all Markdown. Flag explicit fabrication, representing failure as success, bypassing controls/approvals, or unrestricted consequential action. Exclude bounded automation, retries, documentation, tests and quoted counterexamples. Stop with inconclusive for unresolved remote/dynamic operative prompts; missing recommended wording alone is not a failure. statusCriteria: pass: Operative instructions do not require or permit fabrication, control or approval bypass, treating failure as success, or unrestricted consequential action. fail: Operative instructions explicitly require or permit at least one of those behaviors. inconclusive: Potentially unsafe wording is ambiguous, or repository evidence cannot establish whether the identified instructions are operative. - id: AUTH-001 title: Use Microsoft Entra authentication for Azure AI Search level: recommendation rationale: Microsoft Entra authentication avoids distributing Search API keys and supports identity-based access control for hosted-agent retrieval. guidance: - title: "Azure AI Search role-based access control" link: "https://learn.microsoft.com/azure/search/search-security-rbac" - title: "Enterprise knowledge-agent connection configuration" link: "https://github.com/microsoft/Foundry-Agent-Solution-Templates/blob/main/enterprise-knowledge-agent/scripts/provision.py" when: >- Apply to an established runtime Azure AI Search client or linked Search tool/connection. Skip inactive examples and generic APIs without Search evidence; unresolved relevant references are inconclusive. checks: >- Inspect actual Search client credential arguments, directly referenced credential factories, or linked Search connection auth types. A manifest hook creating the runtime connection is valid evidence: locate the referenced connection name or variable and its auth-type/authenticationType declaration, including agentic-identity or managed identity. Entra token credentials and Entra-based connections qualify; AzureKeyCredential, api-key headers or API-key connections fail even when keys come from Key Vault. Search environment names are locators only. Toolbox authentication alone and credentials used solely to run provisioning do not prove runtime Search auth. Stop at unavailable downstream auth configuration; do not inspect indexes, secrets or proxy internals. statusCriteria: pass: Every established Search runtime path uses Entra with no key fallback. fail: Any established Search runtime path uses a key or active key fallback, even if other paths are unresolved. inconclusive: No key violation is proven, but relevant runtime Search authentication remains unresolved. - id: IMG-001 title: Pin prebuilt hosted-agent images by digest level: recommendation rationale: An immutable image digest makes hosted-agent deployments reproducible and prevents a mutable tag from silently selecting different image contents. guidance: - title: "Azure Container Registry image tagging and versioning" link: "https://learn.microsoft.com/azure/container-registry/container-registry-image-tag-version" - title: "Private-network hosted-agent existing ACR scenario" link: "https://github.com/microsoft/Foundry-Agent-Solution-Templates/tree/main/private-network-hosted-agent/scenarios/existing-private-acr" when: >- Apply when the selected service consumes a prebuilt image. Skip source/remote-build services without an image and Dockerfile base images; unresolved deployment mode is inconclusive. checks: >- Start with the selected service image field. A final @sha256:<64 hexadecimal characters> reference passes; a final tag-only reference fails. Resolve directly referenced local variables. Follow a pipeline only if selected by the caller or explicitly linked by active configuration. Accept digest resolution or a gate that validates and deploys the same value; possible manual bypass is outside that scoped result. State the entry point. Unresolved values/transformations are inconclusive; do not search unrelated CI or treat standalone validators as enforced gates. statusCriteria: pass: The submitted image is digest-pinned or the selected entry point enforces pinning of that same value. fail: The selected resolved deployment submits a tag-only or implicit-latest image. inconclusive: Deployment mode, final image or selected pipeline pinning cannot be resolved. - id: NET-001 title: Preserve private-only access in repository-managed recovery level: warning rationale: Automatically opening public access or sending private workload data to a public fallback during recovery defeats an explicitly configured private-only access boundary. guidance: - title: "Foundry hosted-agent virtual networks" link: "https://learn.microsoft.com/azure/foundry/agents/how-to/virtual-networks" - title: "Private-network hosted-agent security boundaries" link: "https://github.com/microsoft/Foundry-Agent-Solution-Templates/blob/main/private-network-hosted-agent/docs/security.md" when: >- Apply when linked active resource configuration or an explicit resource contract establishes private-only access. Skip permitted public access, including deployments with optional Private Endpoints. Names alone are insufficient; unresolved boundaries are inconclusive. checks: >- Locate publicNetworkAccess=Disabled, public_network_access_enabled=false or the explicit private-only contract. Inspect selected deployment hooks and resource-call error handlers plus directly called local recovery helpers; locate matching blocks, not whole libraries. Fail only for reachable recovery that opens the same resource publicly or sends its protected data to a public alternative. Same-endpoint retries, VPN, identity/control-plane access and documented platform exceptions are allowed. Hostnames alone do not prove routing. Stop on unresolved helpers. State inspected executable paths and excluded external image internals; this is not live network assurance. statusCriteria: pass: At least one associated executable local runtime/deployment path is resolved and all inspected paths preserve the boundary or stop. IaC/manifest settings alone cannot establish pass; state coverage and exclusions. fail: A reachable recovery action opens the private resource publicly or redirects its protected data to a public alternative; proven violations take precedence. inconclusive: No violation is proven, but the boundary or an invoked recovery helper is unresolved, or no associated executable local path is inspectable. - id: CFG-001 title: Do not override platform-managed runtime configuration level: warning rationale: >- Overriding platform-injected FOUNDRY_* or AGENT_* runtime variables can break hosted-agent behavior. guidance: - title: "Review platform environment variables" link: "https://learn.microsoft.com/azure/foundry/agents/how-to/configure-hosted-agent-env-variables#review-platform-environment-variables" when: Apply when hosted-agent runtime or deployment configuration is present. checks: >- Check selected service environmentVariables, linked container ENV, and entry-point/startup environment assignments for FOUNDRY_* or AGENT_*, including deprecated FOUNDRY_TOOLBOX_ENDPOINT. Follow direct assignment sources only. Reads, platform outputs and deployment-tool values do not violate this rule unless assigned into the hosted process. Exclude local-only development settings. Unresolved injection or precedence is inconclusive; do not search unrelated scripts. statusCriteria: pass: Inspected deployed runtime configuration does not assign reserved variables. fail: Repository configuration assigns a reserved FOUNDRY_* or AGENT_* variable into the hosted runtime. inconclusive: Runtime injection or configuration precedence cannot be resolved. - id: PROTO-001 title: Keep declared protocols consistent with runtime handlers level: warning rationale: >- Declared hosted-agent protocols must match the deployed handlers. guidance: - title: "Hosted-agent protocol endpoints" link: "https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-contract#protocol-endpoints" - title: "Add a protocol adapter" link: "https://learn.microsoft.com/azure/foundry/agents/how-to/add-protocol-adapter" when: Apply when the hosted-agent service declares the Responses or Invocations protocol in azure.yaml; otherwise skip this rule. checks: >- Compare selected service protocols[].protocol with its entry point and directly referenced registrations. Examples: responses uses ResponsesHostServer, ResponsesAgentServerHost or POST /responses; invocations uses InvocationsHostServer, InvocationAgentServerHost or POST /invocations. Accept equivalent official wiring and valid custom handlers, not just these names. An official host wired to an agent/handler suffices without inspecting SDK internals. Fully resolved mismatches fail; unresolved or dynamic registration is inconclusive. Do not run the server. statusCriteria: pass: Every declared Responses/Invocations protocol maps to a statically identifiable host and handler. fail: A resolved entry point maps a declared protocol incorrectly or its complete static registrations omit the endpoint. inconclusive: Entry point, adapter or handler registration cannot be resolved.