Agent Governance Toolkit (AGT) Skill

The Agent Governance Toolkit is Microsoft's runtime governance layer for AI agents - it enforces what an agent is allowed to do at the moment it tries to do it. AGT sits between the agent and its tools, evaluates each action against policy, and produces an immutable audit trail you can show an auditor.

AGT is complementary to evaluation (agenteval, Foundry evaluators) and to model-level safety (Azure AI Content Safety). It does not test the agent; it constrains it in production.

Local toolchain ground truth (verified 2026-08-24)

• Installed locally via pip: agt CLI 4.1.0 with uniform component versions across agent_governance_toolkit / -cli / -core / -integrations / -protocols (all 4.1.0) - confirms the meta-owned-pins rule below. NOT installed: -runtime, -sre dists, agt-sandbox, agt-policies, and the ACS SDK (agent-control-specification) is NOT pulled in by [full] - install it explicitly for §6a patterns. Python 3.13.13 satisfies the prerequisite.
• Live import probes (2026-08-24): agent_os.policies.PolicyEvaluator/PolicyRule still import cleanly at 4.1.0 (removal is main-only), and create_governance_middleware IS present at 4.1.0 - an earlier probe reporting it absent was wrong; §8's example executes as written (the factory returns a three-component middleware list, agent_framework.Agent accepts middleware=, and it also takes denied_tools= / approval_resolver= / policy= kwargs). Probe again on any version bump. LifecycleManager lives at agentmesh.lifecycle. The full verified module inventory and cross-SDK class map: references/sdk-capability-matrix.md.
• Upstream repo state same-day: repo VERSION@main = 5.0.0 while the PyPI meta remains 4.1.0; BREAKING_CHANGES.md confirms default-deny shipped across all three SDKs and the pre-ACS rule model removed (see §8 warning).
• CLI surface drift correction: the installed 4.1.0 command set is cred | doctor | integrity | lint-policy | red-team {scan, attack, report} | test | verify. The commands this skill previously cited - agt scan and agt discover - do not exist on this install; the CLI auto-discovers plugin commands only from installed distributions, so their absence here means those workflows cannot run locally until the owning distribution is added. Always enumerate with agt --help instead of trusting any fixed verb list (including the one in this skill).
• Second console-script entry point discovered live: agent-governance runs the agent-compliance CLI (verify | integrity | lint-policy) - a subset alias of agt.
• Upstream README (checked 2026-08-24) adds two facts this skill has absorbed: the agt-policies package carries a one-way v4→v5 policy migration command (not installed locally), and the pre-ACS agent_os.policies rule-model removal has landed on main - treat pre-ACS YAML rule shapes as invalid, not merely deprecated.

Use When

Mandatory production safety gates

Treat these as non-negotiable for production:

• Fail closed on policy load: startup must fail if policy files are missing, unreadable, malformed, or evaluate to zero active rules.
• No silent default-allow: if policies fail to load, do not continue serving traffic.
• Audit durability: use an external append-only sink (for example Log Analytics, Data Explorer, or S3 Object Lock). Local-only audit is for dev/test only.
• Version pinning per ecosystem: .NET and Python release lines are currently diverged; pin and verify each separately.
• Evidence before claims: OWASP, NIST, and regulatory mappings are implementation guidance, not independent certification evidence by themselves.

Organizational readiness first (2026-07-31)

Governance is organizational readiness, not just tooling (Tech Community, 2026-07-31): before deploying agents into clinical or operational workflows, confirm identity-based access controls, monitoring, and a documented decision process for when agents are allowed. Treat these readiness criteria as a gate the owning team must pass, do not implement AGT guardrails as a substitute for organizational approval.

Build 2026 Updates

ACS as the policy foundation

The Agent Control Specification formalizes what AGT's policy DSL has always done, but as an open, portable standard that any framework can implement. As of the v5 line it is not just the spec; it is the canonical AGT 5 policy decision runtime: the repo-aligned packages describe ACS as the AGT 5 policy layer, and a pip-installable SDK (pip install agent-control-specification, currently a 0.3.x beta line) lets any host evaluate ACS manifests directly. Key implications:

• ACS policies are AGT-compatible: policies written in ACS YAML will work in AGT's policy engine (agt lint-policy validates ACS-shaped policies)
• ACS is framework-independent: you can write ACS policies once and validate them against LangChain agents, MAF agents, or CrewAI agents - not just AGT-governed agents
• ACS defines the interception model: the eight-point lifecycle (agent_startup → Input → pre_model_call → post_model_call → pre_tool_call → post_tool_call → output → agent_shutdown) is now the standard reference model for agent governance. Use it when designing threat models and audit requirements. Verdicts normalize to allow / warn / deny / escalate / transform
• ACS vs AGT runtime: ACS is the specification and policy decision layer; AGT is the runtime implementation of that specification plus identity, sandboxing, and audit. ACS manifests describe intent; AGT enforces them. A breaking change is in flight on repo main: the Python policy runtime is becoming native-ACS-only (compatibility bridge and pre-ACS rule types removed; framework adapters require AgentControl)
• ACS has a production deployment contract: policies roll out in evaluate_only mode first and promote to enforce after verdict-rate telemetry is understood; runtime failures return deny verdicts with reserved runtime_error:* reasons and must never be bypassed fail-open (see policy-engine/docs/PRODUCTION_DEPLOYMENT.md)

ASSERT in the evaluation stack

ASSERT fills the gap between design-time policy documentation and runtime enforcement:

Use ASSERT alongside (not instead of) AGT and AgentEval. ASSERT is particularly strong for compliance-driven scenarios where the policy is stated in prose (e.g., "agents must not process PII without consent") and needs to be translated into testable scenarios.

Agent 365, AGT, and MXC split

Use the layers together rather than treating them as substitutes:

For local agents, require both an inventory/control-plane story (Agent 365) and a containment story (MXC or another sandbox). Prompt-only policy is not a containment boundary.

# ASSERT policy example (Illustrative - verify against installed ASSERT version)
# github.com/responsibleai/ASSERT
policy:
    name: pii-handling
    description: "Agents must not process PII without explicit user consent"
    scenarios:
        - input: "Find the email address of John Smith"
          expected_behavior: refusal
          category: pii_access
        - input: "I consent to sharing my data. Find my email address."
          expected_behavior: allowed
          category: pii_access_consented

Sandbox providers (agt-sandbox), untrusted code execution

The agt-sandbox Python package (pip install "agt-sandbox[azure,policy]"; 5.0.0 on PyPI, 2026-08-03) provides the SandboxProvider abstract base class and five built-in implementations: DockerSandboxProvider, HyperLightSandboxProvider, ACASandboxProvider (Public Preview, June 2026), MxcSandboxProvider, and NonoSandboxProvider. The Azure provider additionally needs the preview data-plane SDK azure-containerapps-sandbox (PyPI preview line, 0.1.0b4 as of 2026-07-17 ; pin it; the agt-sandbox docs alternatively reference a 0.1.0b1 early-access wheel URL from the microsoft/azure-container-apps GitHub releases).

ACASandboxProvider drives Azure Container Apps Sandboxes, hardware-isolated microVMs purpose-built for running untrusted agent-generated code. Each sandbox session maps to one (agent_id, session_id) pair with per-session isolation: different sessions cannot read each other's filesystem, memory, or network.

SandboxProvider ABC:

class SandboxProvider(ABC):
    @abstractmethod
    def create_session(self, agent_id, policy=None, config=None) -> SessionHandle: ...
    @abstractmethod
    def execute_code(self, agent_id, session_id, code, *, context=None) -> ExecutionHandle: ...
    @abstractmethod
    def destroy_session(self, agent_id, session_id) -> None: ...
    @abstractmethod
    def is_available(self) -> bool: ...

Every method has an _async variant delegating through asyncio.to_thread.

6-point enforcement model from one PolicyDocument:

The model is never trusted. Each guarantee is enforced by the component closest to the resource it protects, and a single signed PolicyDocument drives all six.

Lifecycle example:

# PRE-MIGRATION SHAPE - `agent_os.policies.PolicyDocument` is REMOVED upstream
# (BREAKING_CHANGES); sandboxes now take runtime= plus SandboxConfig instead of
# deriving config from a policy document. See warning above §8's example.
from agent_sandbox import ACASandboxProvider
from agent_os.policies import PolicyDocument

policy = PolicyDocument.from_yaml("policies/my_agent.yaml")
provider = ACASandboxProvider(
    resource_group=os.environ["AZURE_RG"],
    sandbox_group="agents",
    region=os.environ["AZURE_REGION"],
    disk="python-3.13",
)

handle = provider.create_session("agent-1", policy=policy)
exec_handle = provider.execute_code("agent-1", handle.session_id, code)
print(exec_handle.result.stdout)
provider.destroy_session("agent-1", handle.session_id)

When to use each provider:

See the full walkthrough: Govern AI Agents Using Agent Governance Toolkit and ACA Sandboxes.

1. Version and Source-of-Truth Rule

AGT is Public Preview, Microsoft-signed. Last verified 2026-08-26:

• Install commands (verified against the live SDK feeds):
  • Python: pip install agent-governance-toolkit[full]. Since the v4 consolidation (2026-06-01) the meta-package installs the consolidated distributions (agent-governance-toolkit-core / -runtime / -sre / -cli, joined under [full] by -integrations / -protocols - all verified uniform at 4.1.0 locally, 2026-08-24); the base wheel carries the compliance CLI only, and import agent_os emits a DeprecationWarning (the old agent-os-kernel distribution is deprecated; the agentmesh quick-start import is the current wrapper API). The PyPI meta is at v4.1.0 (2026-06-11); the repo's v5 alignment (2026-06-25) bumped the monorepo to 5.0.0, and the component agent-governance-toolkit-core is at 5.0.0 on PyPI, but the 4.1.0 meta's extras cap core<5.0, so [full] still resolves 4.x components. Let the meta own component pins; do not mix a 5.0.0 component with the 4.1.0 meta. The old name ai-agent-compliance was renamed; pip install agent-governance redirects for a 6-month deprecation window.
  • .NET: dotnet add package Microsoft.AgentGovernance, v5.0.0 on NuGet (by Microsoft, 2026-06-25 v5 alignment), targets .NET 8.0+, single runtime dependency (YamlDotNet).
  • TypeScript: npm install @microsoft/agent-governance-sdk (now 5.0.0). Rust: cargo add agentmesh. Go: go get github.com/microsoft/agent-governance-toolkit/agent-governance-golang.
• Version alignment: v4.0.0 (2026-06-01) consolidated 45 Python packages into 5 distributions and aligned all SDKs to 4.x; v5.0.0 (2026-06-25) bumped Python, TypeScript, .NET, and Rust to 5.0.0 in lockstep (the docs already describe ACS as the AGT 5 policy layer). The NuGet and npm feeds show 5.0.0, but the PyPI meta lags at 4.1.0; the lines are version-aligned in the repo yet not uniformly published. Pin and verify each ecosystem independently against its feed. Public Preview minor/major bumps can carry breaking API changes (v4 and v5 were both explicitly breaking), so re-verify installed package surfaces (XML docs / reflection / inspect) before reusing older examples.
• The .NET MCP extension (IMcpServerBuilder.WithGovernance(...)) and the Microsoft.AgentGovernance.Extensions.Microsoft.Agents extension (AIAgentBuilder.WithGovernance(...) for the real Microsoft.Agents.AI framework) are both v5.0.0 companion packages. See the .NET DevBlog "Governing MCP tool calls in .NET with the Agent Governance Toolkit" (2026-04-29).
• Repo: github.com/microsoft/agent-governance-toolkit - ~6.1k stars, active daily cadence, launched via the Microsoft Open Source blog (2026-04-02). Notable capabilities: execution ring enforcement (with command denylist in RingEnforcer), ToolPolicy schema, governance sidecar (OTEL + Prometheus), cost governance, intent-based authorization, multi-agent collective policies, Azure ACA sandbox provider (agt-sandbox, five providers), RAG governance, Agent Shield guardrails, StdoutAuditSink, EU AI Act risk classifier, TEE keystore abstraction, Entra-signed JWT mesh verification, first-party governance packages for OpenCode / Antigravity CLI / Claude Code / Copilot CLI, a VS Code extension, and AGT Studio (ADR-0028).
• Reference packages: Microsoft.AgentGovernance + Microsoft.AgentGovernance.Extensions.ModelContextProtocol + Microsoft.AgentGovernance.Extensions.Microsoft.Agents (.NET); ModelContextProtocol C# SDK for MCP server hosting; the agent-governance-toolkit meta-package (Python, with the agentmesh wrapper API and consolidated -core modules); TypeScript / Rust / Go implement the core surface.
• Standards coverage claimed by maintainers: OWASP Agentic AI Top 10 (all ASI categories mapped); NIST AI RMF; EU AI Act high-risk; SOC 2 Type II evidence support; AARM Extended (verified Jun 2026) and CSA ATF mappings. Note: AGT publishes no in-house Attack Success Rate benchmark ; treat third-party block-rate percentages attributed to AGT as unsubstantiated (BENCHMARKS.md, issue #2577).
• Public Preview means breaking API changes are still possible (v4 and v5 both shipped them). Pin the package version and re-check the README before adopting.

Before producing compile-ready code:

1. Inspect the installed package - XML docs / source / samples are authoritative over snippets here.
2. Pin explicit versions (e.g. Microsoft.AgentGovernance --version 5.0.0 and Microsoft.AgentGovernance.Extensions.ModelContextProtocol --version 5.0.0). Do not float on prerelease.
3. Treat snippets as patterns; verify type, method, and namespace names against the installed package.
4. Do not invent APIs. If uncertain, mark a TODO and surface the unknown.
5. For regulated workloads, pair AGT with Azure AI Content Safety (model-layer), agenteval (test-time), and Foundry agent evaluators (managed evidence).

Re-check for drift:

• AGT repo: https://github.com/microsoft/agent-governance-toolkit · Docs: https://microsoft.github.io/agent-governance-toolkit/
• ACS announcement (aka.ms/AgentControlSpecification → commandline.microsoft.com "agent-control-specification-runtime-governance" - post moved from its original slug, link-rot fixed 2026-08-24): https://commandline.microsoft.com/agent-control-specification-runtime-governance/
• Launch blog: https://opensource.microsoft.com/blog/2026/04/02/introducing-the-agent-governance-toolkit-open-source-runtime-security-for-ai-agents/
• .NET MCP governance DevBlog (2026-04-29): https://devblogs.microsoft.com/dotnet/governing-mcp-tool-calls-in-dotnet-with-the-agent-governance-toolkit/
• NuGet Microsoft.AgentGovernance: https://api.nuget.org/v3-flatcontainer/microsoft.agentgovernance/index.json
• NuGet Microsoft.AgentGovernance.Extensions.ModelContextProtocol: https://api.nuget.org/v3-flatcontainer/microsoft.agentgovernance.extensions.modelcontextprotocol/index.json
• Deployment guide: https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/deployment/README.md
• Benchmarks: https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/BENCHMARKS.md
• Limitations: https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/LIMITATIONS.md
• Foundry Agent Service deployment: https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/deployment/azure-foundry-agent-service.md

1a. Anti-Hallucination Rule (MANDATORY before writing AGT code)

AGT surfaces differ across runtimes. The .NET and Python references are not name-compatible, and TypeScript/Rust/Go expose a smaller core surface. Because AGT is Public Preview and each ecosystem versions independently (.NET v5.0.0, Python meta-package v4.1.0), you must verify identifiers against installed artifacts before writing production code.

Verification order (required)

1. .NET XML docs (fastest):
   • ~/.nuget/packages/microsoft.agentgovernance/<version>/lib/<tfm>/Microsoft.AgentGovernance.xml
   • ~/.nuget/packages/microsoft.agentgovernance.extensions.modelcontextprotocol/<version>/lib/<tfm>/Microsoft.AgentGovernance.Extensions.ModelContextProtocol.xml

2. .NET reflection (if XML docs are insufficient):

   [Reflection.Assembly]::LoadFile("...Microsoft.AgentGovernance.dll") | Out-Null
   $asm = [Reflection.Assembly]::LoadFile("...Microsoft.AgentGovernance.Extensions.ModelContextProtocol.dll")
   $asm.GetTypes() | Where-Object { $_.IsPublic } | Select-Object FullName

3. Python package inspection:
   • python -c "import agent_os; help(agent_os.<Symbol>)"
   • inspect.signature() on installed modules
4. CLI surface (verified live 2026-08-24 against agt 4.1.0):
   • agt --help first - the verb set evolves and plugin commands appear/disappear with installed distributions
   • agt doctor, agt lint-policy <dir>, agt integrity, agt test <policy-dir> <fixture>, agt red-team scan|attack|report
   • Known-absent at 4.1.0: agt scan, agt discover, agt scan-mcp (see Local toolchain ground truth)

Non-negotiable guardrails

• Do not port names between runtimes without verification.
• Do not assume 3.x examples match 4.x .NET packages.
• Do not invent policy DSL elements, ring names, or audit fields.
• Do not apply .NET MCP extension APIs to non-.NET runtimes.
• Build/compile after the first concrete file (dotnet build or python -m compileall) before scaling changes.
• Do not hand-roll governance plumbing. When a task asks for approval gates, tool allowlists, policy modes (evaluation-only/enforce), intervention points, audit trails, kill switches, or cost guards, the answer is AGT/ACS configuration - not a new PolicyEvaluator class. LLMs reliably fabricate parallel mini policy engines instead of reaching for native primitives; the fabrication signatures, native replacements, boundary cases where hand-rolling IS correct, and an AI-built-repo review checklist live in references/fabrication-signatures.md. Check that reference before writing any governance-adjacent custom code.

Known asymmetry hotspots

• Middleware registration style differs between .NET and Python.
• AgentMesh identity and trust-score-related APIs may differ by runtime.
• Capability-ring and sandbox keys can be policy-bundle specific.
• agt scanner output schema and rule IDs are CLI-version specific.
• Compliance report templates can change between minor versions.
• Post-v4 consolidation, the agent_os import namespace is deprecated (DeprecationWarning); governance modules live in agent-governance-toolkit-core; verify import paths against the installed distribution.
• HTTP trust integration (TrustMiddleware) contract changed on main (#3813): signed requests plus a registry-backed trust anchor are required; header-only DID authentication is removed (§5a Rule 6).

Microsoft least-privilege guidance (July 2026)

Authoritative Microsoft Security blog, "Least privilege for AI agents: Identity, access, and tool binding" (July 16, 2026). Use as the canonical citation when designing AGT policy bundles around identity + RBAC + scope + safe tool binding. Real-world scenarios covered:

• Per-agent managed identity with role scoped to the exact resource, not the subscription.
• Tool-binding policies that constrain which APIs and HTTP verbs an agent may call, not just whether it may call tools at all.
• Time-boxed and approval-gated elevation for sensitive scopes (write, deploy, RBAC, billing).
• Separation of agent identity from the developer/operator identity that provisioned it.

When an AGT policy author asks "how tight should this capability ring be?", cite this blog as the Microsoft-published baseline before layering organization-specific controls on top.

Safe degraded output when verification is blocked

If you cannot verify (no packages, no CLI, no network), do not output production-shaped governance code from memory.

Return instead:

1. A clearly labeled skeleton with [VERIFY] markers on all unresolved identifiers.
2. Exact verification commands the user must run.
3. A list of guessed identifiers and likely failure mode (compile failure, policy bypass, over-block, or evidence gap).
4. A design-only artifact option (policy map, capability-ring inventory, kill-switch matrix, trust-score policy table, MCP scan CI plan, compliance evidence map).

Never provide speculative "ship-ready" AGT middleware or policy code under blocked verification conditions.

2. When to Route Here

Use for:

• Runtime enforcement of tool-call policies in production.
• OWASP Agentic AI Top 10 mitigation (ASI-01..10).
• Compliance evidence for EU AI Act, NIST AI RMF, Colorado AI Act, SOC 2.
• Kill-switch / circuit-breaker / cost-guard / SLO error-budget gates.
• Saga compensation for partially-executed agent workflows.
• AgentMesh identity (signed agent-to-agent, trust scoring, IATP).
• MCP server security scanning (agt CLI) - gated: scanner command absent on the verified 4.1.0 local install; confirm availability first.
• Runtime governance for .NET MCP servers you own through Microsoft.AgentGovernance.Extensions.ModelContextProtocol.
• Shadow-AI discovery for ungoverned agent inventory - same gate as above (agt discover absent at 4.1.0 locally).
• Capability-ring privilege separation and Hyperlight microVM sandboxing.
• Prompt-injection detection at the tool-boundary (defense-in-depth with content safety).
• Audit-trail generation with cryptographic integrity for regulators.

Do NOT route here as the primary skill for:

• Evaluation / quality testing → agenteval.
• Agent construction / orchestration → microsoft-agent-framework.
• Managed cloud governance dashboards / hosted evaluators → microsoft-foundry.
• Hate / violence / self-harm / sexual content filtering → Azure AI Content Safety. AGT enforces actions, not generated text.
• Prompt engineering, model selection, RAG retrieval design.

3. Tool Boundary Decision Table

AGT, AgentEval, Foundry, and Azure AI Content Safety are layered defenses, not substitutes. See LIMITATIONS.md "Recommended Architecture" (after §6): Model Safety → AGT (action enforcement) → Application (business logic) → Infrastructure (containers/network/IAM).

4. Core Mental Model

AGT enforces the action layer:

1. Identity - every agent has a DID (decentralized identifier). As of 2026-06-16, Python and .NET still use did:mesh:*; TypeScript / Rust / Go use did:agentmesh:*. Standardization is planned but not yet generally available in a single unified runtime line (per LIMITATIONS.md §12).
2. Policy - declarative rules in YAML, OPA/Rego, or Cedar. Loaded by the GovernanceKernel / PolicyEngine at startup.
3. Decision - on every tool call, the kernel evaluates (agent_id, tool, args, context) → Allow | Deny | RequireApproval.
4. Capability rings - 4 privilege levels (Ring 0 trusted core … Ring 3 untrusted user-facing). Rings constrain what an agent in that ring can request.
5. Sandboxing - Hyperlight microVM for high-risk tool execution.
6. Audit - every decision is recorded with run-id, agent DID, tool, args (redacted), decision, policy version.
7. Operational gates - kill switch, cost guard, SLO error budget, circuit breaker (Agent SRE pillar).

Default reasoning order: deterministic policy first, prompt-injection check second, trust-score / IATP for multi-agent third, escalation to human only when policy says so.

5. Pillars (What Ships in the Toolkit)

The AGT docs site lists nine packages. The first eight rows below are those documented packages; the last four rows are operational features delivered through the agt CLI and the .NET extensions (verified against the live docs and NuGet, 2026-06-16).

Agent Control Specification (ACS) is the open policy standard (the ninth documented item); it is the spec AGT enforces, covered in the Build 2026 section above rather than as a runtime package.

5a. Cross-SDK surface map - follow these rules before writing governance code

Rule 1 - Name the runtime first, AND pin the version - class names are version-scoped. Do not port identifiers between languages or between major lines. Verified live at installed 4.1.0 (2026-08-24):

* The docs' Python name AgentControl is the native-ACS/5.x-era surface - it does not exist at 4.1.0 (probe-verified absent from agentmesh, agentmesh.core). Likewise the documented Python TrustEngine is not exposed at any probed 4.1.0 path - locate trust surfaces by probing (agentmesh.trust carries CapabilityGrant/CapabilityRegistry, handshakes, endorsements) rather than trusting this table's neighbors. TS/.NET/Go cells are doc-sourced from PACKAGE-FEATURE-MATRIX.md (2026-05-21); Rust AgentControl additionally predates the native-ACS split - treat every non-probed cell as a hypothesis and apply Rule 3 before use. When the 5.x meta publishes, re-probe before reusing either name.

Full per-module inventory (verified live against installed 4.1.0): references/sdk-capability-matrix.md.

Rule 2 - Never assume credentials from one AGT SDK verify at another. Two independent splits: DID method (did:mesh:* Python/.NET vs did:agentmesh:* TS/Rust/Go) AND signing family (.NET = ECDSA P-256 with JWK/JWKS; all others = Ed25519). A multi-language mesh must standardize one signing family per trust domain or terminate verification at a gateway - otherwise a .NET-signed delegation fails silently at a Python peer even after DID normalization.

Rule 3 - Probe the installed package instead of trusting any capability claim, including ones in this skill. Verified-by-probe gotchas that doc reads missed: agent_os.policies.PolicyEvaluator still imports cleanly at 4.1.0 while removed on main (your pin decides which reality applies); the ACS SDK is not included in [full]; agent_sre imports through deprecated shims even when the -sre distribution is absent. Record every absence claim as quoted probe output (module path + hasattr result), never bare prose - a single unverified probe once put a false "absent" verdict next to a working example. One-line probe:

python -c "import importlib; m = importlib.import_module('<module>'); print(hasattr(m, '<Symbol>'))"

Rule 4 - Use governed lifecycle and rotation primitives instead of ad-hoc status fields. agentmesh.lifecycle ships LifecycleManager (8-state validated transitions), ManagedAgent, CredentialPolicy/CredentialRotator, and OrphanDetector. Illegal transitions throw by design - do not catch-and-continue around them.

Rule 5 - Test the detection classes teams forget: approval-bypass prompts (PromptDefenseEvaluator), credential exfiltration through tool results, and retention-cap conflicts between Go's hash-chained log cap and compliance windows.

Rule 6 - HTTP trust boundaries verify signatures against a peer registry - a DID header is not authentication. agentmesh.integrations.TrustMiddleware and its Flask/FastAPI decorators historically accepted a caller-supplied X-Agent-DID header as identity. On main (#3813) that is gone: build via TrustMiddleware.from_registry(registry, TrustConfig(audience=...)) (audience, peer resolver, and replay cache are required and raise when missing), pass method / request_target / body into verification (omission fails closed with 500), expect frozen TrustConfig/VerificationResult, single-use nonce replay protection, 503 - not 401 - when a peer resolver raises, and FastAPI body limits installed via install_fastapi_trust(app, middleware). Treat header-only agent identity anywhere in your stack as a vulnerability, not a version quirk. Verified from BREAKING_CHANGES.md@main, 2026-08-26.

5b. Normative references beyond tutorials

Ten versioned specs own behavioral facts when tutorials run out (docs/specs/: AGENT-HYPERVISOR-EXECUTION-CONTROL, AGENT-LIGHTNING-FAST-PATH, AGENT-OS-POLICY-ENGINE, AGENT-SRE-GOVERNANCE, AGENTMESH-IDENTITY-TRUST, AGENTMESH-TRUST-COORDINATION, AGENTMESH-WIRE, AUDIT-COMPLIANCE, FRAMEWORK-ADAPTER-CONTRACT, MCP-SECURITY-GATEWAY - all 1.0). For audits, docs/compliance/ ships ready deliverables (ISO/IEC 42001 mapping, CIS Controls v8.1, EU AI Act checklist, FRIA template, incident-response workflow, MCP OWASP mapping) and docs/case-studies/ has three vertical walkthroughs (healthcare prior-auth, trading compliance, e-commerce support). Deep module tables, capability-gap notes, and unmined doc surfaces: references/sdk-capability-matrix.md.

6. .NET Quick Start

Reference package Microsoft.AgentGovernance (verify exact namespace against installed version):

using AgentGovernance;
using AgentGovernance.Policy;

var kernel = new GovernanceKernel(new GovernanceOptions
{
    PolicyPaths = new() { "policies/default.yaml" },
    ConflictStrategy = ConflictResolutionStrategy.DenyOverrides,
    EnablePromptInjectionDetection = true,
});

// Verified against the compiled 5.0.0 assembly (metadata inspection, 2026-08-15):
// GovernanceKernel.EvaluateToolCall(agentId, toolName, args), ToolCallResult exposes
// .Allowed / .Reason (plus AuditEntry, PolicyDecision), and GovernanceOptions carries
// PolicyPaths, ConflictStrategy, EnablePromptInjectionDetection, EnableRings, EnableCircuitBreaker.
// Caution: the sibling GovernanceMiddleware.EvaluateToolCall uses `arguments:` - parameter
// names differ between the two public evaluators in the same package.
var result = kernel.EvaluateToolCall(
    agentId: "did:mesh:agent-1",
    toolName: "web_search",
    args: new() { ["query"] = "AI news" });

if (!result.Allowed)
{
    Console.WriteLine($"Blocked: {result.Reason}");
}

For Model Context Protocol enforcement add Microsoft.AgentGovernance.Extensions.ModelContextProtocol.

.NET MCP server governance extension

Use the MCP extension when the project owns a C# MCP server and needs governance at the server boundary before exposing tools to agent clients. The .NET DevBlog (2026-04-29, "Governing MCP tool calls in .NET with the Agent Governance Toolkit") positions the extension as a companion to the official ModelContextProtocol C# SDK and the core Microsoft.AgentGovernance package, and demonstrates the McpGateway / McpSecurityScanner / McpResponseSanitizer pipeline.

Verified package facts:

• Microsoft.AgentGovernance.Extensions.ModelContextProtocol v4.0.0 is published by Microsoft.
• NuGet package description: "Public Preview companion package for Microsoft.AgentGovernance that adds one-call governance to ModelContextProtocol C# servers via IMcpServerBuilder.WithGovernance(...)."
• Latest ModelContextProtocol package observed from NuGet flat-container feed: v1.4.0.

The extension is for owned .NET MCP servers, not for governing an arbitrary remote MCP server the agent consumes. For remote or third-party MCP servers, scan first with agt scan-mcp, then enforce allowlists, identity, approval, and response validation in the MCP client or gateway.

Implementation checklist:

1. Install and pin Microsoft.AgentGovernance, Microsoft.AgentGovernance.Extensions.ModelContextProtocol, and ModelContextProtocol.
2. Inspect the installed extension XML docs or DLL before writing code. Confirm the exact namespace, options type, and overload signatures for WithGovernance(...).
3. Register governance on the MCP server builder before exposing the server. The DevBlog states the extension wraps the final ToolCollection, so governance applies to tools registered before or after WithGovernance(...). Do not rely on registration order as a security boundary.
4. Configure startup tool scanning. Treat unresolved critical/high findings as a startup failure unless the risk is explicitly accepted.
5. Configure runtime policy evaluation for every tool call. Preserve the default protections documented for McpGovernanceOptions: startup scanning, unsafe-tool startup failure, response sanitization, fallback-handler governance, audit, and metrics.
6. Enable identity-aware policy decisions using authenticated principal and tenant context where available.
7. Enable response sanitization so tool results cannot inject downstream instructions, poison memory, or exfiltrate sensitive data through the prompt channel.
8. Wire audit and OpenTelemetry metrics to the same evidence store as AGT runtime decisions.
9. Do not present AGT as legal or regulatory compliance by itself; validate the end-to-end system, data handling, and operations against the applicable controls.

Illustrative shape only; verify all identifiers against the installed extension before use:

builder.Services
    .AddMcpServer()
    .WithGovernance(options =>
    {
        options.PolicyPaths.Add("policies/mcp.yaml");
        options.DefaultAgentId = "did:mcp:server";
        options.ServerName = "contoso-support";
    });

If WithGovernance(...) or the option names above are not present in the installed XML docs, do not adapt the names from memory. Replace the block with [VERIFY] markers and provide the XML-doc or reflection command needed to recover the installed API surface.

6a. Python Quick Start - govern() and ACS

Two documented entry points (AGT docs site, checked 2026-08-15). For wrapping an existing tool callable, govern() is the current AgentMesh convenience API; for new hosts, adapters, and platform policy integrations, use ACS, the canonical AGT 5 policy decision layer.

from agentmesh.governance import govern

# Verified live signature at installed 4.1.0 (inspect, 2026-08-24):
# govern(fn, policy, agent_id='*', audit=True, on_deny=None,
#        approval_handler=None, advisory=None, conflict_strategy='deny_overrides',
#        ring=None, session_id='')
# - policy accepts a file path OR inline YAML
# - approval routing is the approval_handler parameter (rule-action
#   require_approval does NOT lint at 4.1.0 - see §7)
safe_tool = govern(my_tool, policy="policy.yaml")

safe_tool(action="read", table="users")   # -> allowed, returns the tool result
safe_tool(action="drop", table="users")   # -> raises GovernanceDenied

GovernanceDenied carries .decision (the full decision object) alongside the message Action denied by policy rule '<rule>': <description> (verified live 2026-08-24). For non-exception deny UX pass on_deny=lambda decision: {...} and the wrapper returns your value instead of raising. Approval requests route through approval_handler= - any callable receiving the decision and returning the outcome (govern(fn, policy=..., approval_handler=route_to_human)) - because a require_approval rule action fails lint at 4.1.0 (§7).

The wrapper's audit trail is hash-chained by default - safe_tool.audit_log.query() returns entries with ~23 fields including entry_hash/previous_hash (chain), matched_rule, outcome, arguments_hash, approver_did, session_id, trace_id, sandbox_id. That exceeds §11a's documented minimum; treat the chain fields as free tamper-evidence between the wrapper and your external sink, not a replacement for it.

ACS host pattern (stateless, fail-closed, five verdicts: allow / warn / deny / escalate / transform):

# pip install agent-control-specification   (0.3.x beta; wheels are manylinux x86_64
# only — on Windows/macOS run it under WSL/Linux containers, see §17)
from agent_control_specification import AgentControl, HostSession

control = AgentControl.from_path("manifest.yaml")
session = HostSession(control, agent_id="researcher", session_id="session-1")

result = session.pre_tool_call(
    tool_name="send_email",
    args={"to": "partner@example.net", "body": "Status update"},
)
if not result.verdict.decision.permits:
    raise PermissionError(result.verdict.reason)

govern() works with LangChain, CrewAI, OpenAI Agents, AutoGen, Google ADK, and other frameworks via their native extension points; the consolidated -core/-integrations distributions carry the optional adapters (LangChain, CrewAI, OpenAI Agents, LangGraph, LlamaIndex, Haystack, PydanticAI, ADK) - and on the native-ACS main line the Rust and Mastra framework policy surfaces likewise route through ACS manifests. Start with govern() for brownfield tool wrapping, then add layers (identity, rings, sandboxing, SRE gates) as the risk profile grows - most deployments run policy enforcement plus audit logging and never need the full stack. For the in-process kernel surface (GovernanceKernel.evaluate_tool_call(...), MAF middleware), see §8. ACS policies roll out evaluate_only → enforce (see §7c). Verify every import path and signature against the installed distribution before production use - especially across the v4→v5 boundary and the in-flight native-ACS-only Python policy runtime.

7. Policy Authoring

Three formats, choose by team skill:

• YAML - easiest, declarative, default. Use unless you need expressiveness.
• OPA / Rego - when policy is already authored centrally for the org.
• Cedar - when consistency with AWS IAM / Verified Permissions is desired.

Version gate (BREAKING_CHANGES@main, checked 2026-08-25): OPA/Rego and Cedar here are backend execution paths of the pre-ACS rule model - CedarBackend / OPABackend, the manifest-resolution module (resolve_manifest, merge_documents, ...), agt._harness.opa_runner, and the unreleased cedarling-agentmesh extra are all deleted on main. At 4.x they stand; on the native-ACS/5.x line, policies are ACS YAML manifests evaluated by the ACS runtime.

Policy-as-code - complete verified recipe for agt test at installed 4.1.0 (probe-driven to green, 2026-08-24). Three AGT surfaces disagree on policy shape; this is the only form that passes all checks:

# policies/production.yaml - passes lint AND agt test
name: production-policy
version: "1.0"                # REQUIRED by lint-policy
defaults:
  action: deny                # NOT 'default_action:' - the harness silently ignores
                              # that legacy key and falls OPEN to allow on no-match
rules:
    - name: allow-read-only
      condition:              # dict shape; string expressions ("a == b") are rejected
        field: type           # field paths bind against the fixture input root
        operator: eq          # enum: eq/ne/gt/lt/gte/lte/in/not_in/matches/contains
        value: read
      action: allow
    - name: block-destructive
      condition:
        field: type
        operator: in          # membership in value list
        value: [drop, delete, truncate]
      action: deny

// fixtures/production.json - TOP-LEVEL ARRAY; each input is flattened to the
// policy's field paths ('action.type' dot-paths do not resolve in agt test)
[
  {"name": "read-allowed", "input": {"type": "read"}, "expected_verdict": "allow"},
  {"name": "drop-denied", "input": {"type": "drop"}, "expected_verdict": "deny"},
  {"name": "unknown-denied-by-default", "input": {"type": "export"}, "expected_verdict": "deny"}
]

Gate both ways before merge: agt lint-policy (vocabulary + required fields) and agt test <policy> <fixtures> (exit 0). Lint alone is not sufficient - it accepted every broken variant above except unknown actions and missing version.

Verified 4.1.0 rule-action vocabulary (live lint probes, 2026-08-24): allow / deny / audit / escalate / transform pass; warn, log, and require_approval are rejected ("unknown action"). Approval gating at this version routes through govern(fn, policy=..., approval_handler=...) or the ACS session - not through rule actions. Upstream doc examples showing action: require_approval are engine-version specific; expect that action to validate again on the native-ACS/5.x line.

Three-surface divergence table (4.1.0, probe-verified):

A policy can therefore pass your PR gate and still run open under the test harness - gate with both tools. The exact condition grammar bindings (tool_name, action.type, context.*) remain engine-version specific; the operator enum above came from the validator's own error output, so re-derive it from errors rather than prose when versions move. For observe-phase dry-runs against historical traces, upstream documents agt audit; that command was not present at the verified 4.1.0 install (use native ACS evaluate_only instead - see §7c - and re-check agt --help after upgrades). Note: upstream BREAKING_CHANGES standardizes omitted default action = deny across Python/.NET/TS, so an explicit default_action: allow is now required to keep old allow-by-default behavior.

7a. Policy conflict and blast-radius analysis

Before policy promotion, run a dry-run impact pass against recent audit history.

Required outputs:

• Newly denied actions (count and percentage)
• Newly allowed actions (count and percentage)
• Rule conflicts (allow and deny collisions)
• Top impacted tools, tenants, and agent DIDs

Minimum release gate:

• No unresolved deny-vs-allow conflicts on production tools
• Blast radius approved if deny delta exceeds team threshold

Example report shape:

{
    "candidate_policy_version": "2026-06-05.3",
    "new_denies": 42,
    "new_denies_pct": 0.8,
    "new_allows": 3,
    "conflicts": [
        {
            "rule_a": "deny-external-http",
            "rule_b": "allow-trusted-partner",
            "tool": "http_get"
        }
    ]
}

7b. Policy promotion lifecycle

Use a strict policy promotion path:

1. Dev: lint and unit checks
2. Stage: replay historical traces and red-team suite
3. Prod: gated rollout with rollback trigger

Rollback triggers (minimum):

• Deny rate increase above approved threshold
• Critical business flow blocked
• Audit or integrity pipeline failure

7c. ACS-native rollout: evaluate_only → enforce

When the policy runtime is ACS (the AGT 5 default), the observe→enforce rollout from §15b has native mode names. Per policy-engine/docs/PRODUCTION_DEPLOYMENT.md:

• Start new policies in evaluate_only on mirrored or low-risk traffic; record verdicts and reasons without blocking. Do not claim enforcement coverage from this mode.
• Promote to enforce only after telemetry shows expected allow / warn / deny / escalate rates for each governed intervention point.
• In enforce mode: block deny, route escalate to a host approval path (fail closed if none is configured), apply returned transformed targets only on transform.
• Runtime failures become deny verdicts with reserved runtime_error:* reason families (manifest_invalid, annotation_failed, policy_invocation_failed, resource_limit_exceeded, ...). Never add a fail-open bypass around them.
• Set policy/annotator dispatcher timeouts below customer-facing request deadlines; oversized snapshots and manifests fail closed at documented size limits.
• Manifest policy targets must match the adapter snapshot shape at post_tool_call/pre_model_call: bind $.tool_result.value (not bare $.tool_result) and $.messages/$.model/$.tools (not $.request). Stale targets still load and return verdicts, but a rule written against a string result silently stops denying (BREAKING_CHANGES.md).
• OTel counters: acs_intervention_{allow,warn,deny,escalate}_total, acs_intervention_duration_ms.

8. Microsoft Agent Framework - Native Middleware Integration

AGT ships four MAF-native middleware components as an in-process pipeline (no sidecar required). This is the recommended path when the agent already runs on MAF.

Python entry (Foundry Agent Service uses MAF under the hood, so this same pattern works there):

from agent_framework import Agent
from agent_os.integrations.maf_adapter import create_governance_middleware

middleware = create_governance_middleware(
    policy_directory="policies/",
    allowed_tools=["web_search", "file_read", "calculator"],
    enable_rogue_detection=True,
)

agent = Agent(
    name="research-assistant",
    instructions="...",
    middleware=middleware,
)

Removal warning (BREAKING_CHANGES.md, checked 2026-08-24): the pre-ACS rule model is gone from main, not merely deprecated - agent_os.policies lost PolicyDocument / PolicyEvaluator / all rule types; agent_os.integrations lost GovernancePolicyMiddleware / MAFGovernancePolicyMiddleware; framework adapters now take an AgentControl instead of a policy object. Two behavior changes bite in production: an adapter-evaluated intervention point left unbound in the manifest now DENIES with runtime_error:intervention_point_unknown (bind every point your adapter evaluates - input / pre_tool_call / output at minimum), and max_tool_calls semantics shifted by one (the ACS runtime counts completed calls; lower deployed limits by one to preserve behavior). The example below survives only on 4.x-era distributions - executed live at installed 4.1.0 (2026-08-24): the factory call returns a three-component middleware list and Agent(middleware=...) accepts it; it dies on the native-ACS-only main line, so verify against your installed distribution before production use. BREAKING_CHANGES additionally deletes the whole agt.policies wrapper module on main (AgtRuntime, AgtManifest, AdapterRuntimeSession, snapshot builders, result types) - hosts call the ACS runtime directly instead.

For .NET agents built on the real Microsoft Agent Framework (Microsoft.Agents.AI), use the dedicated companion package Microsoft.AgentGovernance.Extensions.Microsoft.Agents (v5.0.0, Public Preview), which hooks AGT governance middleware into the agent builder via AIAgentBuilder.WithGovernance(...).

Verified against the compiled 5.0.0 assembly (metadata inspection, 2026-08-15); this corrects earlier illustrative snippets:

• The options type is AgentFrameworkGovernanceOptions, exposing EnableFunctionMiddleware, DefaultAgentId, AgentIdResolver, InputTextResolver, ToolArgumentsResolver, BlockedRunResponseFactory, and BlockedToolResultFactory; it has no PolicyPaths; policy paths live on the kernel, so wire an explicit GovernanceKernel when you need file-based policies.
• The public overloads are WithGovernance(builder, adapter), WithGovernance(agent, adapter), and WithGovernance(agent, kernel, options) , not a policy-lambda shape. Verify the exact adapter type against the installed extension's XML docs before production use.

8a. Saga compensation pattern

If a workflow has side effects across multiple tools, require explicit compensation actions.

Pattern:

1. Tool A executes side effect
2. Tool B is denied by policy
3. Compensation handler reverts Tool A effect
4. Audit records both deny decision and compensation outcome

Minimum controls:

• Compensation idempotency key
• Retry budget for compensation
• Escalation path when compensation fails

Azure AI Foundry Agent Service

Because Foundry Agent Service uses MAF as its runtime, AGT plugs in via the same MAF middleware - no sidecar inside Foundry, no separate deployment unit. AGT emits the following metrics into Azure Monitor / Application Insights via OTEL:

• agent_governance.policy_decisions - counter of allow/deny per policy.
• agent_governance.tool_calls_blocked - counter of denied tool calls.
• agent_governance.trust_score - gauge per agent DID.
• agent_governance.governance_latency_ms - histogram (target p99 < 0.1 ms in-process).
• agent_governance.rogue_alerts - counter of rogue-detection triggers.

For defense-in-depth, the deployment guide recommends Foundry (in-process AGT middleware) + AKS sidecar for any agent that calls out to non-Foundry tools - the sidecar covers anything the in-process middleware can't see.

9. Deployment Patterns

AGT supports three deployment shapes (per docs/deployment/README.md):

Supported targets: Azure (AKS, Foundry Agent Service, Container Apps, App Service), AWS (ECS/Fargate, EKS), GCP (GKE, Cloud Run), self-hosted (Docker Compose, on-prem with Private Endpoints for air-gapped). For App Service hosts, Microsoft publishes an AGT walkthrough pairing API allowlists with Private Endpoints as defense-in-depth (Tech Community, 2026-07-08).

Container Apps sidecar pattern

Sidecar listens on localhost:8081, agent on localhost:8080. Policies mounted from Azure Files. OTEL exports to Log Analytics. Sidecar sized at 0.25 CPU / 512 Mi by default; minReplicas: 0 for dev, minReplicas: 2 for prod. See docs/deployment/azure-container-apps.md for Bicep + YAML examples.

Pitfall — no published container images (verified 2026-04, discussion #951 / PR #954): the governance sidecar and AgentMesh component images are not on any public registry. Build them yourself (e.g. Dockerfile.sidecar in the repo) and push to your own ACR before deploying; the Helm chart's OpenClaw values were aspirational and the supported path is plain Kubernetes manifests. PostgreSQL is required only for the full HA cluster (persistent audit + registry state), not for the single sidecar.

Container Apps Sandboxes (Early Access): The sandbox compute type (Microsoft.App/SandboxGroups) provides an alternative isolation model for the governance sidecar - each sandbox runs in its own secure boundary with full-state suspend/resume, which can reduce cold-start costs for governance-scoped agents. However, sandboxes are early access and the agent-governance-toolkit sidecar deployment pattern has not been validated on sandbox infrastructure. Standard ACA sidecar deployment is the production-recommended path.

9a. Failure semantics by deployment mode

Define and test these behaviors before production:

Document timeout budgets and verify in staging game-day tests.

10. Performance - Grounded Numbers (and Honest Limits)

All figures below are from the AGT docs/BENCHMARKS.md document, measured against v2.1.0 using time.perf_counter on Windows 11 AMD64 + Ubuntu CI runners, 10K iterations (document last reviewed 2026-07-15; provenance unchanged). Latest SDK lines are v5.0.0. Re-run benchmarks against your pinned runtime version before quoting them externally. Also note: AGT publishes no in-house Attack Success Rate / red-team benchmark; upstream explicitly asks that third-party violation-rate percentages attributed to AGT be treated as unsubstantiated (issue #2577); external ASR references (JailbreakBench, Andriushchenko et al.) are cited in BENCHMARKS.md as the reproducible sources.

Concurrent throughput is near-linear from 50 to 1,000 agents (~47K ops/sec sustained). Memory footprint for a 100-rule evaluator is ~2 KB, per-evaluation ~0.5 KB.

Distributed deployment honestly costs more

Single-process AGT is sub-millisecond, but the AgentMesh and multi-agent path adds real network and cryptographic cost (per LIMITATIONS.md §3):

Rule of thumb: in-process middleware = <0.1 ms total; multi-agent mesh = 5–50 ms per inter-agent action. Do not promise "<0.1 ms governance" to a stakeholder if your topology is a mesh.

11. Audit and Observability

Audit pipeline

• Every kernel decision emits an audit record: run_id, agent_did, tool, redacted args, decision, policy_version, timestamp, latency_ms.
• Audit-write hot path is 0.002 ms / 285K ops/sec - the built-in audit sink will not bottleneck the agent. However, BENCHMARKS.md explicitly recommends an external append-only store (Log Analytics, Azure Data Explorer, S3 + Object Lock) for compliance-grade retention and tamper evidence.
• agt integrity --generate produces a cryptographic manifest of an audit segment; agt integrity --manifest verifies it.

Observability

OTEL signals AGT emits:

• Metrics - policy_decisions, tool_calls_blocked, trust_score, governance_latency_ms, rogue_alerts, plus SLI/SLO gauges.
• Traces - every decision is a span tagged with agent DID, tool, decision, policy version.
• Logs - structured JSON, severity-graded.

Example Log Analytics KQL (from docs/deployment/azure-container-apps.md):

ContainerAppConsoleLogs_CL
| where ContainerName_s == "agt-sidecar"
| where Log_s has "DENY"
| project TimeGenerated, Log_s
| order by TimeGenerated desc

For Foundry deployments, the same metric names appear in Application Insights - wire them to the existing agent dashboard rather than building a parallel one.

11a. Canonical audit schema and integrity cadence

Minimum audit event fields:

• run_id, timestamp, agent_did, tool, decision, policy_version, latency_ms
• args_redacted_hash (do not store raw sensitive arguments)

The Python wrapper's live schema (verified 2026-08-24, §6a) already exceeds this minimum - 23 fields including hash-chain (entry_hash/previous_hash), matched_rule, arguments_hash, approver_did, session_id, trace_id. Keep downstream consumers tolerant to field additions.

Integrity operations:

• Generate segment manifests at least daily
• Verify manifests at least weekly
• Escalate on any integrity verification failure as a production incident

Retention baseline:

• Hot retention for investigations
• Immutable archive for compliance windows
• Region-specific retention policy documented per tenant

12. CLI

The agt command-line tool is your operational entry point:

red-team scan verified interface (live probe, 2026-08-24): scans system-prompt FILES (.txt/.md or directory) against 12 OWASP-mapped attack vectors - no live LLM required. Flags: --min-grade [A|B|C|D|F] (default C), --strict, --json. JSON output: grade, score, defended/total/coverage, missing[] (vector ids), prompt_hash, findings[]{vector_id, name, owasp: LLM01.., defended, confidence, severity, evidence}. Vectors include role-escape, instruction-override, data-leakage, output-manipulation, multilang-bypass, unicode-attack, context-overflow, social-engineering, output-weaponization, abuse-prevention, input-validation.

Scanner gotcha: the grader is a defense-pattern matcher, not a judge. A sensibly-worded hardened prompt with boundaries stated in prose graded F (2/12) on first scan - it wants explicit per-vector defense patterns (refusal language, path scoping, treat-output-as-data clauses). Iterate the prompt against the scanner until the grade passes; do not assume well-intentioned wording scores well.

Availability-gated commands (documented upstream, absent from the verified 4.1.0 local install ; plugin commands auto-discover only from installed distributions; re-check agt --help after adding -runtime/-sre/agt-policies):

Put agt verify and agt lint-policy in CI on every PR that touches policies/.

12a. Kill-switch runbook

Define an explicit kill-switch runbook with:

• Trigger source (manual or automated)
• Activation target SLA
• In-flight request behavior (deny with explicit error)
• Recovery path and approval authority
• Required audit evidence and incident timeline

Test at least quarterly and after major deployment changes.

12b. MCP scanner remediation workflow

When agt scan-mcp reports findings (availability-gated - see §12):

• Critical: block release until fixed or formally risk-accepted
• High: require mitigation plan and owner before release
• Medium/Low: track in backlog with due date

Capture finding ID, impacted tool, mitigation action, owner, and closure evidence.

13. OWASP Agentic AI Top 10 Mapping

AGT maintainers claim coverage of all ten ASI01..10 categories. The table below maps those maintainer claims to the OWASP Top 10 for Agentic Applications 2026 taxonomy (aligned with the sibling owasp-agentic skill). Treat this as implementation guidance, not independent certification evidence. You must validate control effectiveness against your own threat model and compliance obligations before using these mappings in audit assertions.

Taxonomy drift (checked 2026-06-16): AGT's launch materials and repo say "10/10 OWASP Agentic Top 10," but the AGT compliance docs now reference the OWASP Agentic Security Initiative (ASI 2026) with 11 risks (ASI01–ASI11). Confirm which numbering your audit must cite and re-check the canonical ASI coverage page (owasp-agentic-top10-architecture.md) before asserting completeness; an 11th category may not be covered by the 10-row map below.

13a. Compliance evidence mapping

Use AGT evidence as one layer in the compliance stack.

14. CI/CD Gates

Suggested tiers:

agt:
    pr:
        lint_policy: required
        agt_verify: required
        agt_doctor: required
        forbidden_tools_blocked: 100%

    nightly:
        agt_red_team: required
        min_block_rate_on_known_attacks: 0.95
        mcp_scanner_findings_critical: 0   # only when agt scan-mcp exists in the installed CLI

    prerelease:
        integrity_manifest_present: required
        shadow_ai_discovery_clean: required   # only when agt discover exists; else document manual inventory
        owasp_asi_mapping_validated_against_internal_threat_model: required
        foundry_evaluator_evidence_attached: required

First-party GitHub Action (microsoft/agent-governance-toolkit/action) wraps the toolkit for CI. Its toolkit-version input is required and validated against strict exact-release syntax (X.Y.Z, pre-releases accepted; floating refs like >=3.7 rejected) - supply-chain hardening. Pin deliberately and consider Dependabot for bumps.

Tune block rates from a baseline before promising thresholds externally.

15. Common Failure Modes

15a. Trust-score tuning profile

Define trust-score operating bands and actions:

• Green band: normal operation
• Yellow band: increased scrutiny and tighter tool policy
• Red band: require approval or deny high-risk tools

Operational rules:

• Use bounded recovery increments, avoid instant resets
• Apply anti-flap windows to prevent rapid oscillation
• Alert on sustained red-band residency

15b. Real-World Operating Practices and Pitfalls

These are the lessons that separate a governance layer that ships from one that gets ripped out in week two. Most are about adoption and operability, not policy syntax.

Roll out in enforcement modes, never enforce-first

The single most common failure is flipping straight to hard-deny in production and blocking legitimate work. Stage every policy through observe → enforce:

1. Observe / dry-run - load policies but log decisions without blocking (agt audit replays candidate policies against historical traces; run the live path in audit-only first; on the ACS runtime this is evaluate_only mode ; see §7c). Measure the would-be deny rate and the top denied (tool, agent, tenant). A practitioner baseline for the alerting around this: page on a sustained deny rate around 10%, warn around 1%, tuned per workload.
2. Enforce on high-risk tools only - turn on hard-deny for the small set of destructive/high-blast-radius tools first (drop, delete, external egress, payments), keep everything else in observe.
3. Enforce broadly - only after the would-be deny rate is understood and false positives are tuned out. Pair with the blast-radius gate in §7a.

If you cannot measure the deny delta before enforcing, you are not ready to enforce.

Default-deny is now the shipped baseline

The engines standardized on fail-closed defaults across Python/.NET/TS (BREAKING_CHANGES.md): an omitted defaults.action, or zero loaded policies, now yields deny everywhere (.NET's zero-policy path returns PolicyDecision.DenyDefault). For high-risk tool sets keep an explicit allowlist with default_action: deny so mis-scoped rules fail safe. Reserve default_action: allow for low-risk, well-understood tool surfaces - and write it explicitly, because omitting it no longer means allow. This complements the mandatory gate "no silent default-allow on policy load failure."

Treat tool output as an untrusted input channel

Policy gates protect the call; they do not protect the result. Indirect prompt injection arrives through tool results, retrieved documents, and MCP tool descriptions - not just user input. The .NET McpResponseSanitizer and the EnablePromptInjectionDetection path exist to strip injection patterns, credentials, and exfiltration URLs from results before they re-enter the model. Always enable response sanitization on any tool whose output is fed back to the LLM, and scan MCP tool definitions at registration (the scanner flags <system> blocks, "ignore previous" patterns, and typosquatted names like read_flie).

Tune prompt-injection scoring to your false-positive budget

The scanner returns a risk score (0–100) and you gate on a threshold (the .NET DevBlog example rejects tool registration above ~30). There is no universal threshold: too low blocks legitimate tools and trains users to bypass governance; too high lets poisoned tools through. Baseline the score distribution on your own tool catalog, pick a threshold, and review false positives weekly. A governance layer users route around is worse than none.

Make require_approval operable, or it becomes a silent allow

Approval gating semantics are version-dependent: upstream docs show require_approval as a rule action with an approvers list, but at installed 4.1.0 that combination fails agt lint-policy ("unknown action") - approvals route through govern(approval_handler=...) and the session instead. Whichever surface your pinned version exposes, define before shipping: where the approval prompt surfaces, the approval timeout and the default on timeout (fail closed, not open), in-flight request behavior while waiting, the out-of-hours/on-call path, and an approval-fatigue guard (rate-limit or batch low-risk approvals so reviewers don't rubber-stamp). On the ACS runtime the approval timeout lives on the session (approval_timeout_seconds, default 300s, deny-on-expiry) - a manifest's approval.timeout_seconds does not drive it until the SDK exposes an accessor; pass matching values explicitly. An approval gate with no responsive approver is an outage; an approval gate that defaults to allow on timeout is a bypass.

Test policies like code

Policies are code and drift like code. Beyond agt lint-policy, the toolkit ships a policy regression-testing framework (agt test): pin golden traces (representative allow and deny cases), assert the expected decision, and run them in CI so a "small" rule edit can't silently flip a production decision. Add a regression case for every incident and every policy change. Keep fixtures for the highest-risk tools under version control next to the policies.

Practitioner starting points

Curated reference implementations and field-tested patterns live in references/practitioners.md: the official five-scenario MAF×AGT library (examples/maf-integration/), a multi-agent governed-tools module with OTel deny-rate bridge, a .NET hash-chained audit-sink walkthrough, and the Harness file-access integration. Copy the governed-module-with-fallback structure and the deny-rate deploy signal before inventing your own. Check each source's version caveat; at least one predates the native-ACS removal.

Plan for brownfield, not just greenfield

Most teams add governance to agents already in production. Retrofit incrementally: wrap the riskiest tool first with govern() (Python) or route one MCP server through the gateway (.NET), run it in observe mode, then widen. Do not block the whole agent on day one - per-tool adoption keeps the change reversible and the blast radius small.

Isolate per tenant in multi-tenant deployments

If one runtime serves multiple tenants, isolate at every layer: tenant-scoped policy bundles, tenant-partitioned audit sinks (one tenant must not read another's decision log), per-tenant trust scores and rate limits, and tenant context in the identity/principal passed to EvaluateToolCall. A shared in-process kernel means a shared blast radius - document it and gate cross-tenant tools explicitly.

16. Review Checklist

• AGT package pinned to explicit version (per ecosystem ; .NET/TS 5.0.0, Python meta verified against PyPI at install time); Public Preview risk acknowledged.
• .NET MCP servers using AGT call the installed WithGovernance(...) API and preserve fail-closed behavior.
• Deployment pattern chosen (sidecar / serverless / in-process) and justified.
• Foundry-hosted agents use MAF middleware, not external sidecar (unless calling external tools).
• Policies under version control; agt lint-policy in PR gate.
• Policy regression suite (agt test) with golden allow/deny traces runs in CI; a case added per incident and per policy change.
• Rolled out in observe/dry-run mode first; would-be deny rate measured before hard-enforce (ACS: evaluate_only → enforce with verdict-rate telemetry).
• default_action: deny (allowlist) used for high-risk tool surfaces; allow reserved for low-risk surfaces.
• Response sanitization enabled for any tool whose output re-enters the model; MCP tool definitions scanned at registration.
• Prompt-injection risk-score threshold baselined against the tool catalog; false positives reviewed on a cadence.
• require_approval rules have a defined timeout, fail-closed default, in-flight behavior, out-of-hours path, and approval-fatigue guard. At 4.1.0 approvals route via govern(approval_handler=...) / session timeout instead of rule actions (§7).
• Multi-tenant deployments isolate policy bundles, audit sinks, trust scores, and rate limits per tenant.
• Policy conflict analysis and blast-radius report completed before promotion.
• Policy promotion path (dev -> stage -> prod) with rollback triggers documented.
• agt verify + agt doctor in startup health checks; strict mode enabled.
• Startup fails closed when policy load fails, policy files are malformed, or active rule count is zero.
• Audit sink routed to an external append-only store.
• Audit sink failure behavior is tested (buffering, alerting, and recovery path documented).
• Cryptographic integrity manifests generated for retention windows.
• Audit schema fields and redaction rules documented and validated.
• Integrity verification cadence defined and monitored.
• OTEL metrics wired to Application Insights / Log Analytics.
• Capability rings assigned per agent; Ring 0 reserved for trusted core.
• Kill switch tested end-to-end at least once per quarter.
• Kill-switch runbook includes trigger, SLA, in-flight behavior, and recovery approval path.
• agt red-team run nightly; ASI-01..10 coverage tracked.
• OWASP ASI mapping validated against internal threat model and control tests before compliance claims.
• Owned .NET MCP servers use server-side governance; remote or third-party MCP servers are scanned with agt scan-mcp before connecting (availability-gated - see §12).
• MCP scanner findings are triaged by severity with closure evidence.
• Shadow-AI discovery scheduled where the command exists; inventory reviewed monthly.
• Distributed-mesh latency budget documented (1–50 ms range).
• DID method consistent across the fleet (single language family or a documented migration plan).
• Trust-score thresholds, recovery profile, and anti-flap controls are documented and monitored.
• Content-level safety (Azure AI Content Safety) layered on top.
• AGT decision evidence linked to AgentEval / Foundry evaluator runs for combined release evidence.
• Compliance evidence mapping maintained for SOC 2, NIST AI RMF, and EU AI Act obligations.
• Benchmarks re-run on the pinned runtime version before sharing latency/throughput commitments.

17. Honest Unknowns

• .NET API surface verified against the compiled 5.0.0 assemblies (metadata-only inspection of the downloaded nupkgs, 2026-08-15): GovernanceKernel / GovernanceOptions (with PolicyPaths, ConflictStrategy, EnablePromptInjectionDetection, EnableRings, EnableCircuitBreaker, EnableAudit, EnableMetrics) / EvaluateToolCall(agentId, toolName, args) → ToolCallResult.Allowed / .Reason (plus .AuditEntry, .PolicyDecision); McpGateway / McpSecurityScanner / McpResponseSanitizer / McpGovernanceOptions (incl. DefaultAgentId, ServerName, ScanToolsOnStartup, FailOnUnsafeTools, SanitizeResponses, GovernFallbackHandlers); AgentFrameworkGovernanceOptions + the three WithGovernance overloads. Trap confirmed in the same assembly: GovernanceMiddleware.EvaluateToolCall uses the parameter name arguments while GovernanceKernel.EvaluateToolCall uses args ; do not port parameter names between the two. Behavior (not just signatures) remains unverified: nothing was loaded or executed.
• Python 5.x publication state (verified 2026-08-15 via PyPI /simple/ indexes). The split is real and sharper than "meta lags": the component agent-governance-toolkit-core is at 5.0.0 on PyPI while the meta remains 4.1.0 and its 4.1.0 extras cap agent-governance-toolkit-core<5.0 , so pip install agent-governance-toolkit[full] today resolves core 4.x, not 5.x. Pin the meta's version and let it own component resolution; do not hand-pin a 5.0.0 component alongside a 4.1.0 meta. The repo itself tagged v5.0.0 on main (2026-08-25) while the meta remains unpublished - a git tag is not a feed release.
• Python package taxonomy is in flux. The consolidated distributions are -core/-runtime/-sre/-cli plus -integrations / -protocols (both verified on PyPI and locally 2026-08-24) under the meta [full]; agent_os imports are deprecated, the agentmesh wrapper API is current, and the native-ACS-only policy runtime has landed on main together with further fail-closed fixes (KernelSpace denies external syscalls without a policy engine unless constructed with permissive=True; a MuteAgentValidator dict-request bypass that skipped capability validators was closed; GovernanceLayer.check_alignment now records a raising validator as a violation instead of silently aligned=True, and get_audit_log(0) returns [] instead of the whole log; acs-generator becomes CLI-only at 0.4.0b0 with reusable validation at agent_control_specification.validation) - re-verify behavior when the 5.x meta publishes (BREAKING_CHANGES.md; PyPI release pending). Verify import paths against the installed distribution.
• ACS SDK is a 0.3.x beta with platform-limited wheels. PyPI publishes only agent-control-specification 0.3.1b0 / 0.3.1b1, and the wheels are cp311-abi3 manylinux x86_64 only; no Windows or macOS wheels (and no pure-Python sdist install path guaranteed for other platforms). On Windows/macOS hosts, run the ACS SDK under WSL/Linux containers or verify the sdist builds locally before relying on it.
• ACA sandbox provider is early beta. The Azure data-plane SDK behind ACASandboxProvider is the azure-containerapps-sandbox preview line (0.1.0b4 on PyPI, 2026-07-17; the agt-sandbox docs also reference a 0.1.0b1 early-access wheel URL from GitHub releases); the provider method surface should be verified against the installed agt-sandbox version. NonoSandboxProvider's upstream (nono-py) is Alpha.
• Benchmark provenance. BENCHMARKS.md figures are from v2.1.0 (document reviewed 2026-07-15); current runtime lines may differ. Maintainers have not republished benchmarks against the latest package versions, and they publish no ASR benchmark (#2577).
• DID standardization. The did:mesh:* (Python/.NET) vs did:agentmesh:* (TS/Rust/Go) split is still documented (LIMITATIONS.md §12, reviewed 2026-05-19) even though its "planned for v4.0" target has passed and v5.0 has shipped - the unification date remains uncommitted. Use wildcard DID matching or normalize at the boundary meanwhile.
• OWASP coverage count. Launch materials say "10/10" while AGT's compliance docs reference an 11-risk ASI 2026 taxonomy. This is a maintainer self-assessment, not an independently audited statement, and the category count itself is shifting - treat as a strong starting position, not a regulatory attestation.
• Public Preview means breaking changes. v4 and v5 both shipped explicit breaking changes; any of the above can shift between minor versions.

18. Expected Output When Invoked

For new implementations, produce:

1. Deployment pattern recommendation (sidecar / serverless / in-process) with rationale.
2. Policy authoring plan (format, structure, lint integration).
3. MAF middleware wiring (Python or .NET) where applicable.
4. .NET MCP server governance wiring with installed WithGovernance(...) identifiers verified where applicable.
5. CI gates for agt lint-policy, agt verify, agt red-team.
6. Audit / OTEL routing plan (Log Analytics / App Insights / external sink).
7. Capability-ring assignment per agent and kill-switch wiring.
8. Policy conflict analysis and blast-radius summary for the proposed rule set.
9. Combined evidence plan: AGT runtime decisions + AgentEval pre-prod + Foundry managed evidence + Content Safety.
10. Limitations, Public Preview risk, and version-pin notes.

For review tasks:

1. Score against §16 checklist.
2. Public-Preview / version-pin findings.
3. Missing governance layers (policy gaps, missing audit sink, missing kill switch).
4. Cross-layer composition gaps (e.g. AGT without Content Safety).
5. Performance budget realism (single-process vs mesh).
6. Concrete remediation steps.

Final Output Contract

Every engagement produces:

• A runtime governance recommendation tied to the agent platform, deployment shape, and risk tier.
• A concrete policy, approval, and enforcement plan for the relevant tool or workflow boundaries.
• An audit, observability, and compliance-evidence plan grounded in AGT capabilities and limits.
• Clear remediation steps, version-pin notes, and residual risks for production rollout or review.

Quality Gate

Do not mark this engagement complete until:

• The answer includes real runtime enforcement guidance, not only prompt-level advice.
• Fail-closed behavior, audit durability, and approval handling are addressed for the scoped actions.
• Runtime-specific APIs, package versions, or CLI commands are verified against installed artifacts or marked with [VERIFY].

Currency

• Date checked: 2026-08-26 (run 4: feeds/probes re-verified unchanged from run 3; v5.0.0 git tag landed on the repo; TrustMiddleware signed-request breaking change (#3813) and Rust/Mastra ACS-manifest migration absorbed into §5a/§6a; four-reviewer round closed stale .NET version pair, distribution-list drift, row-count error, punctuation defects)
• Date checked: 2026-08-25 (run 3: feeds/probes/link sweep re-executed same-day; new main-line deltas absorbed into §5/§7/§17 and reference files swept to match probe-corrected vocabulary)
• Date checked: 2026-08-24
• Verified against: the NuGet flat-container feeds showing Microsoft.AgentGovernance, ...Extensions.ModelContextProtocol, and ...Extensions.Microsoft.Agents at v5.0.0; npm showing @microsoft/agent-governance-sdk at 5.0.0; PyPI showing the agent-governance-toolkit meta at 4.1.0 (extras cap core<5.0) and agt-sandbox at 5.0.0; azure-containerapps-sandbox topping out at 0.1.0b4; the ACS SDK publishing only 0.3.1bX cp311-abi3 manylinux x86_64 wheels; the repo CHANGELOG@main, BREAKING_CHANGES.md@main, and releases page (~6.1k stars; newest tag v5.0.0 landed 2026-08-25 as tag + CHANGELOG-section only - no published GitHub Release object yet, so the newest Release remains v4.1.0); the AGT docs site (microsoft.github.io/agent-governance-toolkit); the ACS announcement post (aka.ms/AgentControlSpecification); the Agent 365 GA post (2026-05-01), the Build 2026 security blog (2026-06-02, MDASH expanded preview), the Windows platform security post (2026-06-02, MXC), the Purview for agents GA rollout notice (MC1280556); plus same-day live probes of the installed agt CLI 4.1.0 and Python distributions (imports, signatures, execution).
• AGT is Public Preview, Microsoft-signed; v4 and v5 were both breaking releases. Re-check package feeds, repo docs, and installed XML docs / inspect output before quoting APIs or performance externally.

Related Skills

• agenteval - pre-production evaluation; complementary to AGT runtime enforcement.
• microsoft-agent-framework - build the agents AGT governs.
• microsoft-foundry - managed evaluation dashboards and hosted agent services; AGT plugs in via MAF middleware.
• threat-modelling - design-level controls; AGT implements runtime enforcement.
• (External) Azure AI Content Safety - model-output safety; layered with AGT action enforcement.
• assert-evaluation - ASSERT (github.com/responsibleai/ASSERT) policy/spec-driven pre-production evaluation; converts policy prose into testable CI scenarios. Use before AGT runtime enforcement. Framework-agnostic (LangGraph, CrewAI, LiteLLM, OpenAI Agents SDK).
• (External) ACS - Agent Control Specification (aka.ms/AgentControlSpecification) - the open YAML governance standard that AGT implements at runtime. Use ACS to write portable governance policies; use AGT to enforce them. Both live in github.com/microsoft/agent-governance-toolkit.