# Technical Documentation: microsoft/agent-governance-toolkit

> ℹ️ **Provenance:** Hybrid Fusion: `microsoft/agent-governance-toolkit` (README + 2 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/microsoft/agent-governance-toolkit) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (microsoft/agent-governance-toolkit)

🌍 [English](/README.md) | [日本語](./docs/i18n/README.ja.md) | [简体中文](./docs/i18n/README.zh-CN.md) | [한국어](./docs/i18n/README.ko.md)



# Agent Governance Toolkit

### Ship agents to production without losing sleep

<p align="center">
  <a href="https://microsoft.github.io/agent-governance-toolkit">
    <img src="https://img.shields.io/badge/%F0%9F%93%96_Full_Documentation-microsoft.github.io%2Fagent--governance--toolkit-0078D4?style=for-the-badge&logoColor=white" alt="Full Documentation" height="40">
  </a>
</p>

<p align="center">
  <strong>
    🚀 <a href="#quick-start">Quick Start</a> ·
    📋 <a href="#specifications">Specifications</a> ·
    📦 <a href="https://pypi.org/project/agent-governance-toolkit/">PyPI</a> ·
    📝 <a href="CHANGELOG.md">Changelog</a>
  </strong>
</p>

[](https://github.com/microsoft/agent-governance-toolkit/actions/workflows/ci.yml)
[](https://discord.gg/TxMRqY3pFr)
[](LICENSE)
[](https://pypi.org/project/agent-governance-toolkit/)
[](https://www.npmjs.com/package/@microsoft/agent-governance-sdk)
[](https://www.nuget.org/packages/Microsoft.AgentGovernance)
[](https://scorecard.dev/viewer/?uri=github.com/microsoft/agent-governance-toolkit)
[](https://www.bestpractices.dev/projects/12085)
[](docs/compliance/owasp-agentic-top10-architecture.md)
[-brightgreen)](https://aarm.dev/builders/agent-governance-toolkit-microsoft)
[](https://agentictrustframework.ai/ecosystem)

> [!IMPORTANT]
> **Public Preview** -- production-quality public preview releases. May have breaking changes before GA.

Policy enforcement, identity, sandboxing, and SRE for autonomous AI agents. One `pip install`, any framework.

---

## The Problem

Your AI agents call tools, browse the web, query databases, and delegate to other agents. Once deployed, they make decisions autonomously. You need answers to three questions:

**1. Is this action allowed?** An agent with access to `send_email` and `query_database` should not be able to `drop_table`. OAuth scopes and IAM roles control which services an agent can reach, not what it does once connected.

**2. Which agent did this?** In a multi-agent system, five agents might share a single API key. When something goes wrong, "an agent did it" is not an incident response.

**3. Can you prove what happened?** Auditors and regulators need tamper-evident records of every decision: what policy was active, what the agent requested, and why it was allowed or denied.

Prompt-level safety ("please follow the rules") is not a control surface. It is a polite request to a stochastic system. [OWASP LLM01:2025](https://genai.owasp.org/llmrisk/llm01-prompt-injection/) states this explicitly: *"it is unclear if there are fool-proof methods of prevention for prompt injection."* The published numbers back this up. [Andriushchenko et al. (ICLR 2025)](https://arxiv.org/abs/2404.02151) report **100% attack success rate** on GPT-4o, GPT-3.5, Claude 3, and Llama-3 using adaptive attacks with logprob access and suffix optimization, evaluated against the [JailbreakBench](https://arxiv.org/abs/2404.01318) benchmark (Chao et al., NeurIPS 2024). Microsoft's own [AI Red Teaming Agent](https://learn.microsoft.com/azure/ai-foundry/concepts/ai-red-teaming-agent) formalizes **Attack Success Rate (ASR)**, the rate of policy violations under adversarial input, as the canonical metric for this class of failure. [*Lessons from Red Teaming 100 Generative AI Products*](https://www.microsoft.com/en-us/security/blog/2025/01/13/3-takeaways-from-red-teaming-100-generative-ai-products/) reinforces the point: *"mitigations do not eliminate risk entirely"* and red teaming must be a continuous process because model-layer defenses are probabilistic by construction.

AGT does not try to win that fight inside the prompt. Every tool call, message send, and delegation is intercepted in deterministic application code *before* the model's intent reaches the wire. Actions the AGT kernel denies are not "unlikely." They are **structurally impossible**. That is the difference between asking an agent to behave and making it incapable of misbehaving.

---

## Quick Start

**Prerequisites:** Python 3.11+

```bash
pip install "agent-governance-toolkit[full]"
```

Use the `[full]` extra for the quick-start imports below. The base
`agent-governance-toolkit` wheel installs the compliance CLI only; the governance
modules live in the consolidated core distribution. The `agentmesh` quick-start
import remains the current wrapper API. Importing `agent_os` emits a
`DeprecationWarning` because the old `agent-os-kernel` distribution is deprecated.
Use `agent-governance-toolkit-core` (or the `[full]` extra that includes it) as
the replacement distribution. Policy-engine host code uses the ACS SDK;
`agt-policies` provides the one-way v4-to-v5 migration command. The pre-ACS
`agent_os.policies` rule model is gone, and `BREAKING_CHANGES.md` lists its
replacements.

For Claude Code, add AGT as a plugin marketplace and install the governance plugin:

```text
/plugin marketplace add microsoft/agent-governance-toolkit
/plugin install agt-governance@agent-governance-toolkit
```

Govern any tool function in two lines:

```python
from agentmesh.governance import govern

safe_tool = govern(my_tool, policy="policy.yaml")   # every call checked, logged, enforced
```

On every call, `safe_tool` evaluates the YAML policy, logs the decision to an
audit trail, and raises `GovernanceDenied` when the policy blocks the action.

```yaml
# policy.yaml
apiVersion: governance.toolkit/v1
name: production-policy
default_action: allow
rules:
  - name: block-destructive
    condition: "action.type in ['drop', 'delete', 'truncate']"
    action: deny
    description: "Destructive operations require human approval"

  - name: require-approval-for-send
    condition: "action.type == 'send_email'"
    action: require_approval
    approvers: ["security-team"]
```

```python
>>> safe_tool(action="read", table="users")
{'table': 'users', 'rows': 42}

>>> safe_tool(action="drop", table="users")
GovernanceDenied: Action denied by policy rule 'block-destructive':
  Destructive operations require human approval
```

Or use the full `AgentControl` API for programmatic control:

<details>
<summary><b>AgentControl example</b></summary>

```python
from agent_control_specification import AgentControl

runtime = AgentControl.from_path(str("manifest.yaml"))
result = runtime.evaluate(
    "input",
    {
        "envelope": {"agent_id": "example-agent"},
        "input": {"body": {"action": "web_search", "params": {}}},
    },
)
print(result.verdict)
runtime.close()
```

[Run the complete ACS email-tool example](examples/acs-email-tool).

</details>

<details>
<summary><b>TypeScript / .NET / Rust / Go examples</b></summary>

**TypeScript**
```typescript
import { PolicyEngine } from "@microsoft/agent-governance-sdk";

const engine = new PolicyEngine([
  { action: "web_search", effect: "allow" },
  { action: "shell_exec", effect: "deny" },
]);
engine.evaluate("web_search"); // "allow"
engine.evaluate("shell_exec"); // "deny"
```

**.NET**
```csharp
using AgentGovernance;
using AgentGovernance.Extensions.ModelContextProtocol;
using AgentGovernance.Policy;

var kernel = new GovernanceKernel(new GovernanceOptions
{
    PolicyPaths = new() { "policies/default.yaml" },
});
var result = kernel.EvaluateToolCall("did:mesh:agent-1", "web_search",
    new() { ["query"] = "latest AI news" });

// MCP server integration
builder.Services.AddMcpServer()
    .WithGovernance(options => options.PolicyPaths.Add("policies/mcp.yaml"));
```

**Rust**
```rust
use agent_governance::{AgentMeshClient, ClientOptions};

let client = AgentMeshClient::new("my-agent").unwrap();
let result = client.execute_with_governance("data.read", None);
assert!(result.allowed);
```

**Go**
```go
import agentmesh "github.com/microsoft/agent-governance-toolkit/agent-governance-golang"

client, _ := agentmesh.NewClient("my-agent",
    agentmesh.WithPolicyRules([]agentmesh.PolicyRule{
        {Action: "data.read", Effect: agentmesh.Allow},
        {Action: "*", Effect: agentmesh.Deny},
    }),
)
result := client.ExecuteWithGovernance("data.read", nil)
```

</details>

CLI tools:

```bash
agt doctor                                        # check installation
agt verify                                        # OWASP compliance check
agt verify --evidence ./agt-evidence.json --strict # fail CI on weak evidence
agt red-team scan ./prompts/ --min-grade B         # prompt injection audit
agt lint-policy policies/                          # validate policy files
```

Full walkthrough: [quickstart.md](docs/quickstart.md) -- zero to governed agents in 5 minutes.
🌍 Also in: [日本語](docs/i18n/quickstart.ja.md) | [简体中文](docs/i18n/quickstart.zh-CN.md) | [한국어](docs/i18n/quickstart.ko.md)

---

## How It Works

```
Agent ──► Policy Engine ──► Identity ──► Audit Log
            (YAML/OPA/Cedar)  (SPIFFE/DID/mTLS)  (Tamper-evident)
                 │                                      │
                 ├── Allowed ──► Tool executes           │
                 └── Denied  ──► GovernanceDenied        │
                                                        ▼
                                                 Decision Record
```

Every layer is optional. Start with `govern()` and add layers as your risk profile grows. Most teams run policy enforcement + audit logging and never need the full stack.

---

## Packages

| Package | Description |
|---------|-------------|
| [**Agent OS**](agent-governance-python/agent-os/) | Policy engine, agent lifecycle, governance gate |
| [**Agent Control Specification**](policy-engine/) ([README](policy-engine/README.md)) | Stateless, deterministic, fail-closed policy decision runtime (Rust core) backing the AGT policy layer |
| [**Agent Mesh**](agent-governance-python/agent-mesh/) | Agent discovery, routing, and trust mesh |
| [**Agent Runtime**](agent-governance-python/agent-runtime/) | Execution sandboxing with four privilege rings |
| [**Agent SRE**](agent-governance-python/agent-sre/) | Kill switch, SLO monitoring, chaos testing |
| [**Agent Compliance**](agent-governance-python/agent-compliance/) | OWASP verification, policy linting, integrity checks |
| [**Agent Marketplace**](agent-governance-python/agent-marketplace/) | Plugin governance and trust scoring |
| [**Agent Lightning**](agent-governance-python/agent-lightning/) | RL training governance with violation penalties |
| [**Agent Hypervisor**](agent-governance-python/agent-hypervisor/) | Execution audit, delta engine, in-memory commitment tracking, command denylist enforcement |

### Additional Capabilities

| Capability | Description |
|---|---|
| **MCP Security Gateway** | Tool poisoning detection, drift monitoring, typosquatting, hidden instruction scanning ([Spec](docs/specs/MCP-SECURITY-GATEWAY-1.0.md)) |
| **Shadow AI Discovery** | Find unregistered agents across processes, configs, and repos ([Discovery](agent-governance-python/agent-discovery/)) |
| **Governance Dashboard** | Real-time fleet visibility for health, trust, and compliance ([Dashboard](examples/demos/governance-dashboard/)) |
| **PromptDefense Evaluator** | 12-vector prompt injection audit ([Evaluator](agent-governance-python/agent-compliance/src/agent_compliance/prompt_defense.py)) |
| **Contributor Reputation** | PR/issue author screening for social engineering. Reusable GitHub Action ([Action](.github/actions/contributor-check/)) |

---

## Install

| Language | Package | Command |
|----------|---------|---------|
| **Python** | [`agent-governance-toolkit`](https://pypi.org/project/agent-governance-toolkit/) | `pip install "agent-governance-toolkit[full]"` |
| **TypeScript** | [`@microsoft/agent-governance-sdk`](agent-governance-typescript/) | `npm install @microsoft/agent-governance-sdk` |
| **Copilot CLI** | [`@microsoft/agent-governance-copilot-cli`](agent-governance-copilot-cli/) | `npx @microsoft/agent-governance-copilot-cli install` |
| **Claude Code** | [`@microsoft/agent-governance-claude-code`](agent-governance-claude-code/) | `claude --plugin-dir ./agent-governance-claude-code` |
| **OpenCode** | [`@microsoft/agent-governance-opencode`](agent-governance-opencode/) | `npm install @microsoft/agent-governance-opencode` |
| **.NET** | [`Microsoft.AgentGovernance`](https://www.nuget.org/packages/Microsoft.AgentGovernance) | `dotnet add package Microsoft.AgentGovernance` |
| **.NET MCP** | `Microsoft.AgentGovernance.Extensions.ModelContextProtocol` | `dotnet add package Microsoft.AgentGovernance.Extensions.ModelContextProtocol` |
| **Rust** | [`agent-governance`](https://crates.io/crates/agent-governance) | `cargo add agent-governance` |
| **Go** | [`agent-governance-toolkit`](agent-governance-golang/) | `go get github.com/microsoft/agent-governance-toolkit/agent-governance-golang` |

All five language SDKs implement core governance (policy, identity, trust, audit). Python has the full stack. Copilot CLI and Claude Code are first-party developer surfaces built on the TypeScript SDK.
See **[Language Package Matrix](docs/PACKAGE-FEATURE-MATRIX.md)** for detailed per-language coverage.

<details>
<summary><b>Python distributions (v4.1.0 — consolidated)</b></summary>

As of v4.1.0, 45 packages have been consolidated into 5 top-level distributions:

| Distribution | PyPI | What's included |
|--------------|------|-----------------|
| `agent-governance-toolkit-core` | [`agent-governance-toolkit-core`](https://pypi.org/project/agent-governance-toolkit-core/) | Policy engine, capability model, audit, MCP gateway, zero-trust identity, trust scoring, A2A/MCP/IATP bridges |
| `agent-governance-toolkit-runtime` | [`agent-governance-toolkit-runtime`](https://pypi.org/project/agent-governance-toolkit-runtime/) | Privilege rings, saga orchestration, termination control, execution plan validation, command denylist enforcement |
| `agent-governance-toolkit-sre` | [`agent-governance-toolkit-sre`](https://pypi.org/project/agent-governance-toolkit-sre/) | SLOs, error budgets, chaos engineering, circuit breakers |
| `agent-governance-toolkit-cli` | [`agent-governance-toolkit-cli`](https://pypi.org/project/agent-governance-toolkit-cli/) | `agt` CLI, OWASP verification, integrity checks, policy linting |
| `agent-governance-toolkit[full]` | [`agent-governance-toolkit`](https://pypi.org/project/agent-governance-toolkit/) | Meta-package installing all of the above |

Previous package names (`agent-os-kernel`, `agentmesh-platform`, `agentmesh-runtime`, `agent-sre`, `agent-discovery`, `agent-hypervisor`, `agentmesh-marketplace`, `agentmesh-lightning`) remain installable as stub packages that redirect to the consolidated distributions.

</details>

### Prerequisites

- **Python**: 3.10+
- **Node.js**: 18+ / npm 9+ (TypeScript SDK)
- **.NET**: 8+
- **Go**: 1.25+
- **Rust**: 1.70+
- **Optional**: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` for Azure-integrated features

---

## Framework Support

| Framework | Integration |
|-----------|-------------|
| [**Microsoft Agent Framework**](https://github.com/microsoft/agent-framework) | Native Middleware |
| [**Semantic Kernel**](https://github.com/microsoft/semantic-kernel) | Native (.NET + Python) |
| [AutoGen](https://github.com/microsoft/autogen) | Adapter |
| [LangGraph](https://github.com/langchain-ai/langgraph) / [LangChain](https://github.com/langchain-ai/langchain) | Adapter |
| [CrewAI](https://github.com/crewAIInc/crewAI) | Adapter |
| [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) | Middleware |
| Claude Code | Governance plugin package |
| [Google ADK](https://github.com/google/adk-python) | Adapter |
| [LlamaIndex](https://github.com/run-llama/llama_index) | Middleware |
| [Haystack](https://github.com/deepset-ai/haystack) | Pipeline |
| [Mastra](https://github.com/mastra-ai/mastra) | Adapter |
| [Dify](https://github.com/langgenius/dify) | Plugin |
| [Azure AI Foundry](https://learn.microsoft.com/azure/ai-studio/) | Deployment Guide |
| GitHub Copilot CLI | Governance installer |

Full list: [Framework Integrations](agent-governance-python/agentmesh-integrations/) · [Quickstart Examples](examples/quickstart/)

---

## Examples

| Example | Framework | What it demonstrates |
|---------|-----------|----------------------|
| [acs-email-tool](examples/acs-email-tool) | Framework-neutral ACS host | Snapshot, verdict, transform, deny, and host enforcement |
| [acs-atr-annotator](examples/acs-atr-annotator) | ACS custom policy | Independent threat-rule annotations with fail-closed decisions |
| [openai-agents-governed](examples/openai-agents-governed) | OpenAI Agents SDK | Policy-gated tool calls with trust tiers |
| [crewai-governed](examples/crewai-governed) | CrewAI | Multi-agent governance with role-based policies |
| [smolagents-governed](examples/smolagents-governed) | HuggingFace smolagents | Lightweight agent governance |
| [maf-integration](examples/maf-integration) | MAF | Microsoft Agent Framework integration |
| [mcp-trust-verified-server](examples/mcp-trust-verified-server) | MCP | Trust-verified MCP server implementation |
| [governance-dashboard](examples/demos/governance-dashboard) | Streamlit | Real-time fleet visibility dashboard |

---

## Specifications

Every major component has a formal RFC 2119 specification with conformance tests. These specs define the behavioral contract: what implementations MUST, SHOULD, and MAY do.

| Specification | Scope | Tests |
|---|---|---|
| [Agent OS Policy Engine](docs/specs/AGENT-OS-POLICY-ENGINE-1.0.md) | Native runtime integration and fail-closed semantics | -- |
| [Agent Control Specification](policy-engine/spec/SPECIFICATION.md) | Stateless intervention-point policy runtime, verdicts, transform, fail-closed | -- |
| [AgentMesh Identity and Trust](docs/specs/AGENTMESH-IDENTITY-TRUST-1.0.md) | Credentials, trust scoring, delegation chains | 135 |
| [Agent Hypervisor Execution Control](docs/specs/AGENT-HYPERVISOR-EXECUTION-CONTROL-1.0.md) | Privilege rings, saga orchestration, kill switch | 80 |
| [AgentMesh Trust and Coordination](docs/specs/AGENTMESH-TRUST-COORDINATION-1.0.md) | Peer trust negotiation, mesh-wide policy | 62 |
| [Agent SRE Governance](docs/specs/AGENT-SRE-GOVERNANCE-1.0.md) | SLOs, error budgets, chaos, circuit breakers | 111 |
| [MCP Security Gateway](docs/specs/MCP-SECURITY-GATEWAY-1.0.md) | Tool poisoning, drift detection, hidden instructions | 127 |
| [Agent Lightning Fast-Path](docs/specs/AGENT-LIGHTNING-FAST-PATH-1.0.md) | RL training governance, violation penalties | 100 |
| [Framework Adapter Contract](docs/specs/FRAMEWORK-ADAPTER-CONTRACT-1.0.md) | Native framework mediation contract | -- |
| [Audit and Compliance](docs/specs/AUDIT-COMPLIANCE-1.0.md) | Merkle audit, compliance mapping, Decision BOM | 157 |
| [AgentMesh Wire Protocol](docs/specs/AGENTMESH-WIRE-1.0.md) | Message format, routing, serialization | -- |

**992 conformance tests** ensure code stays aligned to specs. [29 Architecture Decision Records](docs/adr/) document why.

---

## Standards Compliance

| Standard | Coverage |
|----------|----------|
| [OWASP Agentic AI Top 10](docs/compliance/owasp-agentic-top10-architecture.md) | All ASI risk categories mapped with deterministic controls |
| [NIST AI RMF 1.0](docs/compliance/nist-ai-rmf-alignment.md) | Full GOVERN, MAP, MEASURE, MANAGE alignment |
| [EU AI Act](docs/compliance/) | Compliance mapping with automated evidence |
| [SOC 2](docs/compliance/soc2-mapping.md) | Control mapping with audit trail export |
| [AARM Extended](https://aarm.dev/builders/agent-governance-toolkit-microsoft) | All R1–R9 requirements satisfied; verified Jun 14, 2026 |
| [ATF](https://agentictrustframework.ai/ecosystem) | All five elements mapped: Agent Mesh (identity), Agent OS (policy), Agent Compliance (governance), Agent Runtime (sandboxing), Agent SRE (incident response) |

---

## Security

AGT enforces governance at the application middleware layer, not at the OS kernel level. The policy engine and agents share the same process boundary.

**Production recommendation:** Run each agent in a separate container for OS-level isolation. See [Architecture: Security Boundaries](docs/ARCHITECTURE.md).

| Tool | Coverage |
|------|----------|
| CodeQL | Python + TypeScript SAST |
| Gitleaks | Secret scanning on PR/push/weekly |
| ClusterFuzzLite | 7 fuzz targets (policy, injection, MCP, sandbox, trust) |
| Dependabot | 13 ecosystems |
| OpenSSF Scorecard | Weekly scoring + SARIF upload |

See [Known Limitations](docs/LIMITATIONS.md) for honest design boundaries and recommended layered defense.

---

## Documentation

| Category | Links |
|----------|-------|
| **Getting Started** | [Quick Start](docs/quickstart.md) · [Tutorials](docs/tutorials/) (60+) · [FAQ](docs/FAQ.md) |
| **Architecture** | [System Design](docs/ARCHITECTURE.md) · [Threat Model](docs/security/threat-model.md) · [ADRs](docs/adr/) (29) |
| **Specifications** | [All Specs](docs/specs/) (10 formal specs, 992 conformance tests) |
| **API Reference** | [Agent OS](agent-governance-python/agent-os/README.md) · [AgentMesh](agent-governance-python/agent-mesh/README.md) · [Agent SRE](agent-governance-python/agent-sre/README.md) |
| **Compliance** | [OWASP](docs/compliance/owasp-agentic-top10-architecture.md) · [EU AI Act](docs/compliance/) · [NIST AI RMF](docs/compliance/nist-ai-rmf-alignment.md) · [SOC 2](docs/compliance/soc2-mapping.md) · [AARM Extended](https://aarm.dev/builders/agent-governance-toolkit-microsoft) · [ATF](https://agentictrustframework.ai/ecosystem) |
| **Deployment** | [Azure](docs/deployment/README.md) · [AWS](docs/deployment/README.md) · [GCP](docs/deployment/README.md) · [Docker Compose](docs/deployment/README.md) |
| **Extensions** | [VS Code](agent-governance-typescript/agent-os-vscode/) · [Framework Integrations](agent-governance-python/agentmesh-integrations/) |

---

## Contributing

[Contributing Guide](CONTRIBUTING.md) · [Community](docs/COMMUNITY.md) · [Discord](https://discord.gg/TxMRqY3pFr) · [Security Policy](SECURITY.md) · [Changelog](CHANGELOG.md)

**Using AGT?** Add your organization to [ADOPTERS.md](docs/ADOPTERS.md).

## Governance

| Document | Purpose |
|----------|---------|
| [GOVERNANCE.md](GOVERNANCE.md) | Decision-making, roles, contributor ladder |
| [CHARTER.md](docs/CHARTER.md) | Technical charter (LF Projects format) |
| [MAINTAINERS.md](MAINTAINERS.md) | Maintainers and organizations |
| [SECURITY.md](SECURITY.md) | Vulnerability reporting and response SLAs |
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Microsoft Open Source Code of Conduct |
| [ANTITRUST.md](ANTITRUST.md) | Competition law guidelines for participants |
| [TRADEMARKS.md](TRADEMARKS.md) | Trademark usage policy |

## Important Notes

If you use the Agent Governance Toolkit to build applications that operate with third-party agent frameworks or services, you do so at your own risk. We recommend reviewing all data being shared with third-party services and being cognizant of third-party practices for retention and location of data.

## Official Sources

The only official sources for the Agent Governance Toolkit are:

| Resource | Location |
|----------|----------|
| **Source code** | [github.com/microsoft/agent-governance-toolkit](https://github.com/microsoft/agent-governance-toolkit) |
| **Documentation** | [microsoft.github.io/agent-governance-toolkit](https://microsoft.github.io/agent-governance-toolkit/) |
| **Python packages** | [pypi.org/user/agentgovtoolkit](https://pypi.org/user/agentgovtoolkit/) |
| **npm packages** | `@microsoft/agent-governance-sdk` on [npmjs.com](https://www.npmjs.com/) |
| **NuGet packages** | `Microsoft.AgentGovernance.*` on [nuget.org](https://www.nuget.org/) |
| **Rust crates** | `agent-governance`, `agent-governance-mcp` on [crates.io](https://crates.io/) |

The project team does not maintain or endorse any third-party websites,
packages, or documentation sites claiming to be official. If you encounter a
suspicious site or package using the Agent Governance Toolkit name, please
report it through the channels described in [SECURITY.md](SECURITY.md).

## License

This project is licensed under the [MIT License](LICENSE).

## Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must follow
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.

## 2. In-Tree Documentation Chapters (microsoft/agent-governance-toolkit)

### Chapter: index (docs/index.md)

---
title: Agent Governance Toolkit
last_reviewed: 2026-08-03
owner: docs-team
hide:
  - navigation
  - toc
---

<div class="agt-hero" markdown>

<div class="agt-hero-inner" markdown>

<div class="agt-hero-kicker"><span>Public Preview</span><span>Runtime governance for autonomous agents</span></div>

# Ship autonomous agents with enforceable guardrails

<p class="agt-hero-subtitle">ACS provides portable policy controls that your host enforces.<br>Add identity, isolation, and audit around each agent action.</p>

<div class="agt-hero-cta">
  <a class="agt-btn agt-btn-solid" href="quickstart/">Get started</a>
  <a class="agt-btn agt-btn-ghost" href="https://github.com/microsoft/agent-governance-toolkit">
    <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill="currentColor" d="M8 0C3.58 0 0 3.58 0 8a8 8 0 005.47 7.59c.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82a7.42 7.42 0 014 0c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>
    View on GitHub
  </a>
</div>

<div class="agt-hero-install" markdown>

```bash
pip install agent-governance-toolkit[full]
```

</div>

<div class="agt-hero-actions">
  <a class="agt-action" href="packages/">
    <span class="agt-action-label">Package guide</span>
    <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"><path fill="currentColor" d="M3.5 3.5h6a.5.5 0 010 1H4.707l8.147 8.146a.5.5 0 01-.708.708L4 5.207V10a.5.5 0 01-1 0V4a.5.5 0 01.5-.5z"/></svg>
  </a>
  <a class="agt-action" href="tutorials/">
    <span class="agt-action-label">Tutorials</span>
    <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"><path fill="currentColor" d="M3.5 3.5h6a.5.5 0 010 1H4.707l8.147 8.146a.5.5 0 01-.708.708L4 5.207V10a.5.5 0 01-1 0V4a.5.5 0 01.5-.5z"/></svg>
  </a>
  <a class="agt-action" href="ARCHITECTURE/">
    <span class="agt-action-label">Architecture</span>
    <svg viewBox="0 0 16 16" width="14" height="14" aria-hidden="true"><path fill="currentColor" d="M3.5 3.5h6a.5.5 0 010 1H4.707l8.147 8.146a.5.5 0 01-.708.708L4 5.207V10a.5.5 0 01-1 0V4a.5.5 0 01.5-.5z"/></svg>
  </a>
</div>

<div class="agt-capabilities">
  <div class="agt-capability"><span class="agt-capability-name">Policy</span><span class="agt-capability-detail">Stateless, fail-closed decisions</span></div>
  <div class="agt-capability"><span class="agt-capability-name">Trust</span><span class="agt-capability-detail">DID, SPIFFE, mTLS</span></div>
  <div class="agt-capability"><span class="agt-capability-name">Runtime</span><span class="agt-capability-detail">Isolation and kill switches</span></div>
  <div class="agt-capability"><span class="agt-capability-name">Evidence</span><span class="agt-capability-detail">Tamper-evident audit</span></div>
</div>

</div>

</div>

<div class="agt-section" markdown>

## The problem

Your AI agents call tools, browse the web, query databases, and delegate to other agents. Once deployed, they make decisions autonomously. You need answers to three questions:

**1. Is this action allowed?** An agent with access to `send_email` and `query_database` should not be able to `drop_table`. OAuth scopes and IAM roles control which services an agent can reach, not what it does once connected.

**2. Which agent did this?** In a multi-agent system, five agents might share a single API key. When something goes wrong, "an agent did it" is not an incident response.

**3. Can you prove what happened?** Auditors and regulators need tamper-evident records of every decision: what policy was active, what the agent requested, and why it was allowed or denied.

</div>

<div class="agt-section" markdown>

## Start with governance in 2 lines

Wrap a tool function with `govern()` for the shortest application integration.
This is the current AgentMesh convenience API. New hosts, adapters, and platform
policy integrations should use ACS.

```python
from agentmesh.governance import govern

safe_tool = govern(my_tool, policy="policy.yaml")
```

On every call, `safe_tool` evaluates the YAML policy, logs the decision to an
audit trail, and raises `GovernanceDenied` when the policy blocks the action.
Because it wraps a callable, the same pattern works with tools from LangChain,
CrewAI, OpenAI Agents, AutoGen, Google ADK, and any other framework.

```yaml
# policy.yaml
apiVersion: governance.toolkit/v1
name: production-policy
default_action: allow
rules:
  - name: block-destructive
    condition: "action.type in ['drop', 'delete', 'truncate']"
    action: deny
    description: "Destructive operations require human approval"

  - name: require-approval-for-send
    condition: "action.type == 'send_email'"
    action: require_approval
    approvers: ["security-team"]
```

```
>>> safe_tool(action="read", table="users")
{'table': 'users', 'rows': 42}

>>> safe_tool(action="drop", table="users")
GovernanceDenied: Action denied by policy rule 'block-destructive':
  Destructive operations require human approval
```

</div>

<div class="agt-section" markdown>

## ACS is the policy decision layer

[Agent Control Specification](packages/agent-control-specification.md), or ACS,
is the canonical AGT 5 policy decision runtime. At each lifecycle event, the
host sends ACS a complete snapshot, receives a verdict, and applies it at the
corresponding intervention point.

```bash
pip install agent-control-specification
```

```python
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)
```

ACS returns one of five normalized verdicts: `allow`, `warn`, `deny`,
`escalate`, or `transform`. ACS neither executes the tool nor retains hidden
session state, so framework adapters, gateways, and custom hosts can share the
same portable policy contract.

Run `examples/acs-email-tool` from a repository checkout, or follow the
[step-by-step ACS tutorial](tutorials/55-agent-control-specification.md).

</div>

<div class="agt-section" markdown>

## How it works

``` mermaid
flowchart LR
    A["Agent framework"] --> H["AGT host or adapter"]
    H -->|Complete snapshot| ACS["ACS policy decision layer<br>Rego · Cedar · custom"]
    ACS -->|Normalized verdict| H
    H -->|Allow or transformed action| T["Tool executes"]
    H -->|Deny or escalate| B["Block or approval"]
    ID["Identity and trust"] --> H
    H --> AL["Tamper-evident audit"]
    HV["Runtime isolation"] --> T
```

ACS returns the decision; the host applies it. Identity and audit supply context
and evidence, while runtime isolation controls execution. These layers do not
change the ACS decision contract.

</div>

<div class="agt-section" markdown>

## Architecture and package families

<div class="agt-cards">
<a class="agt-card" data-pkg="acs" href="packages/agent-control-specification/">
<img class="agt-card-icon" src="assets/icons/agent-os.svg" alt="">
<span class="agt-card-body"><span class="agt-card-title">ACS policy decision layer</span>
<span class="agt-card-desc">Portable manifests, intervention points, and fail-closed verdicts</span></span>
</a>
<a class="agt-card" data-pkg="compliance" href="packages/#python-toolkit">
<img class="agt-card-icon" src="assets/icons/agent-compliance.svg" alt="">
<span class="agt-card-body"><span class="agt-card-title">Python Toolkit</span>
<span class="agt-card-desc">Recommended install for the complete governance stack</span></span>
</a>
<a class="agt-card" data-pkg="os" href="packages/#python-core">
<img class="agt-card-icon" src="assets/icons/agent-os.svg" alt="">
<span class="agt-card-body"><span class="agt-card-title">Python Core</span>
<span class="agt-card-desc">Policy, trust, identity, audit, and runtime primitives</span></span>
</a>
<a class="agt-card" data-pkg="mesh" href="packages/#framework-integrations">
<img class="agt-card-icon" src="assets/icons/agent-mesh.svg" alt="">
<span class="agt-card-body"><span class="agt-card-title">Framework Integrations</span>
<span class="agt-card-desc">Optional adapters for major agent frameworks</span></span>
</a>
<a class="agt-card" data-pkg="sre" href="packages/#cli-and-operations">
<img class="agt-card-icon" src="assets/icons/agent-sre.svg" alt="">
<span class="agt-card-body"><span class="agt-card-title">CLI and Operations</span>
<span class="agt-card-desc">Operator tooling, SRE, sandboxing, and MCP trust</span></span>
</a>
<a class="agt-card" data-pkg="runtime" href="packages/#protocol-governance">
<img class="agt-card-icon" src="assets/icons/agent-runtime.svg" alt="">
<span class="agt-card-body"><span class="agt-card-title">Protocol Governance</span>
<span class="agt-card-desc">MCP, A2A, receipts, and trust protocol surfaces</span></span>
</a>
</div>
</div>

<div class="agt-section" markdown>

## Language SDKs

| SDK | Install |
|-----|---------|
| [ACS host for Python](packages/agent-control-specification.md#how-python-hosts-call-acs) | `pip install agent-control-specification` |
| [Python](packages/index.md) | `pip install agent-governance-toolkit[full]` |
| [TypeScript](tutorials/20-typescript-sdk.md) | `npm install @microsoft/agent-governance-sdk` |
| [.NET](packages/dotnet-sdk.md) | `dotnet add package Microsoft.AgentGovernance` |
| [Rust](tutorials/21-rust-sdk.md) | `cargo add agentmesh` |
| [Go](tutorials/22-go-sdk.md) | `go get github.com/microsoft/agent-governance-toolkit/agent-governance-golang` |

</div>

<div class="agt-section" markdown>

## Framework Integrations

Use `govern()` to wrap application callables. For framework lifecycle hooks,
hosts use the native ACS Python SDK to build snapshots and enforce verdicts.
Optional adapters cover LangChain, CrewAI, OpenAI Agents, LangGraph,
LlamaIndex, Haystack, PydanticAI, and Google ADK. See the
[package guide](packages/index.md#framework-integrations).

</div>

<div class="agt-section" markdown>

## Examples

| Example | Framework | What it demonstrates |
|---------|-----------|---------------------|
| [acs-email-tool](tutorials/55-agent-control-specification.md) | Framework-neutral ACS host | Runnable source at `examples/acs-email-tool` with snapshot, transform, deny, and host enforcement |
| [acs-atr-annotator](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/acs-atr-annotator) | ACS custom policy | Independent threat-rule annotations with fail-closed decisions |
| [openai-agents-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/openai-agents-governed) | OpenAI Agents SDK | Policy-gated tool calls with trust tiers |
| [crewai-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/crewai-governed) | CrewAI | Multi-agent governance with role-based policies |
| [smolagents-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/smolagents-governed) | HuggingFace smolagents | Lightweight agent governance |
| [maf-integration](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/maf-integration) | MAF | Microsoft Agent Framework integration |
| [mcp-trust-verified-server](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/mcp-trust-verified-server) | MCP | Trust-verified MCP server implementation |

</div>

<div class="agt-section" markdown>

## Specifications and design contracts

These documents define runtime and interoperability contracts. Each page states
its status; listing it here does not imply that every implementation conforms.

| Document | Scope |
|---|---|
| [Agent OS Policy Engine](specs/AGENT-OS-POLICY-ENGINE-1.0.md) | Policy evaluation and enforcement semantics |
| [Agent Control Specification](packages/agent-control-specification.md) | Intervention points, verdicts, transforms, and escalation |
| [AgentMesh Identity and Trust](specs/AGENTMESH-IDENTITY-TRUST-1.0.md) | Identity, credentials, trust scoring, and attestation |
| [Agent Hypervisor Execution Control](specs/AGENT-HYPERVISOR-EXECUTION-CONTROL-1.0.md) | Execution rings, isolation, and recovery |
| [AgentMesh Trust and Coordination](specs/AGENTMESH-TRUST-COORDINATION-1.0.md) | Multi-agent trust and coordination |
| [AgentMesh Wire Protocol](specs/AGENTMESH-WIRE-1.0.md) | Encrypted agent-to-agent messaging |
| [Agent SRE Governance](specs/AGENT-SRE-GOVERNANCE-1.0.md) | Reliability, SLO, and incident controls |
| [MCP Security Gateway](specs/MCP-SECURITY-GATEWAY-1.0.md) | MCP tool mediation and trust enforcement |
| [Agent Lightning Fast-Path](specs/AGENT-LIGHTNING-FAST-PATH-1.0.md) | Governed reinforcement learning workflows |
| [Framework Adapter Contract](specs/FRAMEWORK-ADAPTER-CONTRACT-1.0.md) | Common adapter lifecycle and failure semantics |
| [Audit and Compliance](specs/AUDIT-COMPLIANCE-1.0.md) | Audit events, integrity, evidence, and export |

[Architecture Decision Records](./adr/index.md) document the reasoning behind key design choices.

</div>

<div class="agt-section" markdown>

## Compliance mappings

| Framework | What the documentation provides |
|----------|----------|
| [OWASP Agentic Security Initiative](compliance/owasp-agentic-top10-architecture.md) | Architecture and policy-rule crosswalks for ASI risk categories |
| [NIST AI RMF 1.0](compliance/nist-ai-rmf-alignment.md) | Govern, Map, Measure, and Manage alignment worksheet |
| [EU AI Act](compliance/eu-ai-act-checklist.md) | Readiness checklist and assessment templates |
| [SOC 2](compliance/soc2-mapping.md) | Control-to-evidence mapping with documented gaps |

</div>

### Chapter: quickstart (docs/quickstart.md)

---
title: Quickstart
last_reviewed: 2026-07-12
owner: docs-team
---

# Quickstart

Use a native ACS manifest for policy and an Agent OS adapter for framework
lifecycle mediation.

## Install

```bash
pip install agent-governance-toolkit[full]
```

## Create a starter bundle

```bash
python -m agent_os.cli.cmd_policy_gen \
  --template strict \
  --output policies/
agt lint-policy policies/manifest.yaml
```

The generated directory contains `manifest.yaml` and `policy.rego`. The
manifest binds the Rego policy to native intervention points.

## Evaluate a tool call

```python
from agent_control_specification import AgentControl, HostSession

runtime = AgentControl.from_path("policies/manifest.yaml")
session = HostSession(
    runtime,
    agent_id="quickstart-agent",
    session_id="quickstart-session",
)

evaluation = session.pre_tool_call(
    tool_name="delete_file",
    args={"path": "report.txt"},
)

print(evaluation.verdict)
print(evaluation.reason_code)
```

Attempted tool calls are charged before evaluation, including denied attempts.
The runtime itself remains free of session counters.

## Attach a framework

```python
from agent_os.integrations.langchain_adapter import LangChainKernel

kernel = LangChainKernel(runtime=runtime)
```

Every supported adapter receives the native runtime through `runtime=`. Policy
definitions, blocked content, tool catalogs, budgets, transforms, and approval
belong in the manifest rather than the adapter constructor.

## Handle a denial

```python
from agent_os.exceptions import PolicyViolationError

if not evaluation.verdict.decision.permits:
    error = PolicyViolationError.from_evaluation_result(evaluation)
    print(str(error))
    print(error.evaluation_result.audit_record())
```

The public exception text is sanitized. Trusted code can use the attached
`PolicyEvaluation` for structured audit and dispatch.

## Next steps

- [Agent Control Specification](tutorials/55-agent-control-specification.md)
- [Framework integrations](tutorials/03-framework-integrations.md)
- [Policy testing](tutorials/policy-as-code/06-policy-testing.md)
- [Progressive governance](tutorials/progressive-governance.md)

--- METRICS ---
- Files Extracted: 3
- Estimated Token Budget: ~10316 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/microsoft/agent-governance-toolkit