diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..5ce0953cf --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,57 @@ +name: Deploy docs to GitHub Pages + +on: + push: + branches: [main] + paths: + - 'site/**' + - 'mkdocs.yml' + - 'docs/**' + - '.github/workflows/docs.yml' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install MkDocs Material + run: pip install mkdocs-material mkdocs-minify-plugin + + - name: Copy source docs + run: bash scripts/build-docs.sh + + - name: Build docs + run: mkdocs build --config-file mkdocs.yml --site-dir _site + env: + SITE_URL: https://microsoft.github.io/agent-governance-toolkit + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: _site + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 1c59286d6..78b1cca23 100644 --- a/.gitignore +++ b/.gitignore @@ -454,3 +454,4 @@ FodyWeavers.xsd *.token .env .env.* +_site/ diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..589d86578 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,142 @@ +site_name: Agent Governance Toolkit +site_description: Governance, trust, identity, and compliance for AI agents +site_url: https://microsoft.github.io/agent-governance-toolkit +repo_url: https://github.com/microsoft/agent-governance-toolkit +repo_name: microsoft/agent-governance-toolkit +edit_uri: edit/main/site/docs/ +docs_dir: site/docs + +theme: + name: material + palette: + - scheme: default + primary: indigo + accent: teal + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: indigo + accent: teal + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.instant + - navigation.tracking + - navigation.tabs + - navigation.tabs.sticky + - navigation.sections + - navigation.expand + - navigation.top + - search.suggest + - search.highlight + - content.code.copy + - content.tabs.link + - toc.follow + icon: + repo: fontawesome/brands/github + font: + text: Inter + code: JetBrains Mono + +plugins: + - search + - minify: + minify_html: true + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - attr_list + - md_in_html + - tables + - toc: + permalink: true + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/microsoft/agent-governance-toolkit + generator: false + +nav: + - Home: index.md + - Getting Started: + - Quick Start: quickstart.md + - Architecture: architecture.md + - Glossary: glossary.md + - Packages: + - Overview: packages/index.md + - Agent OS: packages/agent-os.md + - Agent Mesh: packages/agent-mesh.md + - Agent Runtime: packages/agent-runtime.md + - Agent SRE: packages/agent-sre.md + - Agent Compliance: packages/agent-compliance.md + - Agent Marketplace: packages/agent-marketplace.md + - Agent Lightning: packages/agent-lightning.md + - Agent Hypervisor: packages/agent-hypervisor.md + - .NET SDK: packages/agent-governance-dotnet.md + - VS Code Extension: packages/agent-os-vscode.md + - Tutorials: + - Overview: tutorials/index.md + - Policy Engine: tutorials/01-policy-engine.md + - Trust & Identity: tutorials/02-trust-and-identity.md + - Framework Integrations: tutorials/03-framework-integrations.md + - Audit & Compliance: tutorials/04-audit-and-compliance.md + - Agent Reliability: tutorials/05-agent-reliability.md + - Execution Sandboxing: tutorials/06-execution-sandboxing.md + - MCP Security Gateway: tutorials/07-mcp-security-gateway.md + - OPA / Rego / Cedar Policies: tutorials/08-opa-rego-cedar-policies.md + - Prompt Injection Detection: tutorials/09-prompt-injection-detection.md + - Plugin Marketplace: tutorials/10-plugin-marketplace.md + - Saga Orchestration: tutorials/11-saga-orchestration.md + - Liability & Attribution: tutorials/12-liability-and-attribution.md + - Observability & Tracing: tutorials/13-observability-and-tracing.md + - Kill Switch & Rate Limiting: tutorials/14-kill-switch-and-rate-limiting.md + - RL Training Governance: tutorials/15-rl-training-governance.md + - Protocol Bridges: tutorials/16-protocol-bridges.md + - Advanced Trust: tutorials/17-advanced-trust-and-behavior.md + - Compliance Verification: tutorials/18-compliance-verification.md + - .NET SDK: tutorials/19-dotnet-sdk.md + - TypeScript SDK: tutorials/20-typescript-sdk.md + - Rust SDK: tutorials/21-rust-sdk.md + - Go SDK: tutorials/22-go-sdk.md + - Delegation Chains: tutorials/23-delegation-chains.md + - Cost & Token Budgets: tutorials/24-cost-and-token-budgets.md + - Security Hardening: tutorials/25-security-hardening.md + - SBOM & Signing: tutorials/26-sbom-and-signing.md + - MCP Scan CLI: tutorials/27-mcp-scan-cli.md + - Deployment: + - Overview: deployment/index.md + - Azure Container Apps: deployment/azure-container-apps.md + - Azure Foundry Agent Service: deployment/azure-foundry-agent-service.md + - OpenClaw Sidecar: deployment/openclaw-sidecar.md + - Private Endpoints: deployment/private-endpoints.md + - Security: + - Threat Model: security/threat-model.md + - OWASP Compliance: security/owasp-compliance.md + - Security Scanning: security/scanning.md + - Tenant Isolation: security/tenant-isolation.md + - Architecture Decisions: + - Overview: adr/index.md + - "ADR-0001: Ed25519 for Identity": adr/0001-use-ed25519-for-agent-identity.md + - "ADR-0002: Four Execution Rings": adr/0002-use-four-execution-rings-for-runtime-privilege.md + - "ADR-0003: IATP Handshake 200ms": adr/0003-keep-iatp-handshake-within-200ms.md + - "ADR-0004: Deterministic Policy": adr/0004-keep-policy-evaluation-deterministic.md + - Reference: + - Benchmarks: reference/benchmarks.md + - Comparison: reference/comparison.md + - NIST RFI Mapping: reference/nist-rfi-mapping.md + - Changelog: reference/changelog.md + - Contributing: reference/contributing.md diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh new file mode 100755 index 000000000..6a5acadc9 --- /dev/null +++ b/scripts/build-docs.sh @@ -0,0 +1,49 @@ +#!/bin/bash +# Build script for MkDocs documentation site. +# Copies existing docs into site/docs/ so content is maintained in one place. +# Run this before `mkdocs build` or let the GitHub Actions workflow handle it. + +set -e + +SITE_DOCS="site/docs" + +echo "Copying docs to $SITE_DOCS..." + +# Create directories +mkdir -p "$SITE_DOCS"/{packages,tutorials,deployment,security,adr,reference} + +# Top-level docs +cp QUICKSTART.md "$SITE_DOCS/quickstart.md" +cp docs/ARCHITECTURE.md "$SITE_DOCS/architecture.md" +cp docs/GLOSSARY.md "$SITE_DOCS/glossary.md" + +# Tutorials +cp docs/tutorials/*.md "$SITE_DOCS/tutorials/" + +# Deployment +cp docs/deployment/*.md "$SITE_DOCS/deployment/" + +# Security +cp docs/THREAT_MODEL.md "$SITE_DOCS/security/threat-model.md" +cp docs/OWASP-COMPLIANCE.md "$SITE_DOCS/security/owasp-compliance.md" +cp docs/security-scanning.md "$SITE_DOCS/security/scanning.md" +cp docs/security/tenant-isolation-checklist.md "$SITE_DOCS/security/tenant-isolation.md" + +# ADRs +cp docs/adr/*.md "$SITE_DOCS/adr/" + +# Reference +cp BENCHMARKS.md "$SITE_DOCS/reference/benchmarks.md" +cp docs/COMPARISON.md "$SITE_DOCS/reference/comparison.md" +cp docs/nist-rfi-mapping.md "$SITE_DOCS/reference/nist-rfi-mapping.md" +cp CHANGELOG.md "$SITE_DOCS/reference/changelog.md" +cp CONTRIBUTING.md "$SITE_DOCS/reference/contributing.md" + +# Package READMEs +for pkg in agent-os agent-mesh agent-runtime agent-sre agent-compliance agent-marketplace agent-lightning agent-hypervisor agent-governance-dotnet agent-os-vscode; do + if [ -f "packages/$pkg/README.md" ]; then + cp "packages/$pkg/README.md" "$SITE_DOCS/packages/$pkg.md" + fi +done + +echo "Done. $(find $SITE_DOCS -name '*.md' | wc -l | tr -d ' ') pages ready." diff --git a/site/docs/.gitignore b/site/docs/.gitignore new file mode 100644 index 000000000..260190f0f --- /dev/null +++ b/site/docs/.gitignore @@ -0,0 +1,23 @@ +# These files are copied from source by scripts/build-docs.sh at build time. +# Only index pages and the landing page are committed. +quickstart.md +architecture.md +glossary.md +tutorials/[0-9]*.md +tutorials/README.md +deployment/README.md +deployment/azure-*.md +deployment/openclaw-*.md +deployment/private-*.md +security/threat-model.md +security/owasp-compliance.md +security/scanning.md +security/tenant-isolation.md +adr/0*.md +adr/README.md +reference/benchmarks.md +reference/comparison.md +reference/nist-rfi-mapping.md +reference/changelog.md +reference/contributing.md +packages/agent-*.md diff --git a/site/docs/adr/index.md b/site/docs/adr/index.md new file mode 100644 index 000000000..6fe29cbd8 --- /dev/null +++ b/site/docs/adr/index.md @@ -0,0 +1,10 @@ +# Architecture Decision Records + +Key architectural decisions and their rationale. + +| ADR | Decision | +|-----|----------| +| [ADR-0001](0001-use-ed25519-for-agent-identity.md) | Use Ed25519 for agent identity signatures | +| [ADR-0002](0002-use-four-execution-rings-for-runtime-privilege.md) | Four execution rings for runtime privilege separation | +| [ADR-0003](0003-keep-iatp-handshake-within-200ms.md) | Keep IATP handshake under 200ms | +| [ADR-0004](0004-keep-policy-evaluation-deterministic.md) | Keep policy evaluation deterministic | diff --git a/site/docs/deployment/index.md b/site/docs/deployment/index.md new file mode 100644 index 000000000..84c17d301 --- /dev/null +++ b/site/docs/deployment/index.md @@ -0,0 +1,10 @@ +# Deployment Guides + +Deploy AGT across Azure services and container platforms. + +| Guide | Platform | +|-------|----------| +| [Azure Container Apps](azure-container-apps.md) | Managed containers on Azure | +| [Azure Foundry Agent Service](azure-foundry-agent-service.md) | Foundry-native agent hosting | +| [OpenClaw Sidecar](openclaw-sidecar.md) | Sidecar deployment pattern | +| [Private Endpoints](private-endpoints.md) | Secure networking with private links | diff --git a/site/docs/index.md b/site/docs/index.md new file mode 100644 index 000000000..e81c3eb74 --- /dev/null +++ b/site/docs/index.md @@ -0,0 +1,51 @@ +# Agent Governance Toolkit + +**Governance, trust, identity, and compliance for AI agents.** + +The Agent Governance Toolkit (AGT) provides a comprehensive set of packages for building governed, trustworthy AI agent systems. It covers the full lifecycle: policy enforcement, identity management, runtime sandboxing, reliability engineering, compliance verification, and marketplace governance. + +## Quick Links + +| | | +|---|---| +| :material-rocket-launch: [**Quick Start**](quickstart.md) | Get running in 5 minutes | +| :material-cube-outline: [**Packages**](packages/index.md) | 11 packages for every governance layer | +| :material-school: [**Tutorials**](tutorials/index.md) | 27 step-by-step guides | +| :material-cloud-upload: [**Deployment**](deployment/index.md) | Azure Container Apps, Foundry, OpenClaw | +| :material-shield-check: [**Security**](security/threat-model.md) | Threat model, OWASP compliance, scanning | + +## Packages at a Glance + +| Package | Purpose | +|---------|---------| +| [Agent OS](packages/agent-os.md) | Core policy engine and agent lifecycle management | +| [Agent Mesh](packages/agent-mesh.md) | Agent discovery, routing, and trust mesh | +| [Agent Runtime](packages/agent-runtime.md) | Execution sandboxing with privilege rings | +| [Agent SRE](packages/agent-sre.md) | Reliability: kill switch, SLO monitoring, chaos testing | +| [Agent Compliance](packages/agent-compliance.md) | Audit logging, compliance frameworks, evidence collection | +| [Agent Marketplace](packages/agent-marketplace.md) | Plugin governance and marketplace trust | +| [Agent Lightning](packages/agent-lightning.md) | High-performance agent orchestration | +| [Agent Hypervisor](packages/agent-hypervisor.md) | Hardware-level isolation for agent workloads | + +## Examples + +Governed examples for popular AI agent frameworks: + +| Example | Framework | What it demonstrates | +|---------|-----------|---------------------| +| [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 | +| [protect-mcp-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/protect-mcp-governed) | protect-mcp | Cedar policies + Ed25519 signed receipts for MCP tool calls | +| [physical-attestation-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/physical-attestation-governed) | Physical sensors | Cold chain sensor attestation (temperature, shock, GPS) | +| [openshell-governed](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/openshell-governed) | OpenShell | Sandboxed shell execution governance | +| [mcp-trust-verified-server](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/mcp-trust-verified-server) | MCP | Trust-verified MCP server implementation | +| [maf-integration](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/maf-integration) | MAF | Microsoft Agent Framework integration | +| [marketplace-governance](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/marketplace-governance) | Marketplace | Plugin governance and trust scoring | +| [atr-community-rules](https://github.com/microsoft/agent-governance-toolkit/tree/main/examples/atr-community-rules) | ATR | Community-contributed governance rules | + +## Standards + +- **OWASP Agentic AI Top 10** — [compliance mapping](security/owasp-compliance.md) +- **NIST AI RMF** — [RFI response](reference/nist-rfi-mapping.md) +- **Ed25519 (RFC 8032)** — [ADR-0001](adr/0001-use-ed25519-for-agent-identity.md) diff --git a/site/docs/packages/index.md b/site/docs/packages/index.md new file mode 100644 index 000000000..e7961c48a --- /dev/null +++ b/site/docs/packages/index.md @@ -0,0 +1,43 @@ +# Packages + +AGT provides 11 packages covering every layer of agent governance. + +``` ++------------------+ +------------------+ +------------------+ +| Agent OS | | Agent Mesh | | Agent Runtime | +| Policy engine | | Discovery & | | Sandboxing & | +| & lifecycle | | trust mesh | | privilege rings | ++------------------+ +------------------+ +------------------+ + | | | ++------------------+ +------------------+ +------------------+ +| Agent SRE | | Agent Compliance | | Agent Marketplace| +| Reliability & | | Audit logging | | Plugin trust | +| monitoring | | & frameworks | | & governance | ++------------------+ +------------------+ +------------------+ + | | | ++------------------+ +------------------+ +------------------+ +| Agent Lightning | | Agent Hypervisor | | SDK Packages | +| High-perf | | HW isolation | | .NET, TS, Rust | +| orchestration | | for workloads | | Go, VS Code | ++------------------+ +------------------+ +------------------+ +``` + +## Core Packages + +| Package | Description | Install | +|---------|------------|---------| +| [Agent OS](agent-os.md) | Policy engine, agent lifecycle, governance gate | `pip install agent-os` | +| [Agent Mesh](agent-mesh.md) | Agent discovery, routing, trust mesh | `pip install agent-mesh` | +| [Agent Runtime](agent-runtime.md) | Execution sandboxing, four privilege rings | `pip install agent-runtime` | +| [Agent SRE](agent-sre.md) | Kill switch, SLO monitoring, chaos testing | `pip install agent-sre` | +| [Agent Compliance](agent-compliance.md) | Audit logging, compliance frameworks | `pip install agent-compliance` | +| [Agent Marketplace](agent-marketplace.md) | Plugin governance, marketplace trust | `pip install agent-marketplace` | +| [Agent Lightning](agent-lightning.md) | High-performance orchestration | `pip install agent-lightning` | +| [Agent Hypervisor](agent-hypervisor.md) | Hardware-level workload isolation | `pip install agent-hypervisor` | + +## SDK Packages + +| Package | Language | Install | +|---------|---------|---------| +| [.NET SDK](agent-governance-dotnet.md) | C# / .NET | `dotnet add package AgentGovernance` | +| [VS Code Extension](agent-os-vscode.md) | VS Code | Install from marketplace | diff --git a/site/docs/tutorials/index.md b/site/docs/tutorials/index.md new file mode 100644 index 000000000..cbee46a7a --- /dev/null +++ b/site/docs/tutorials/index.md @@ -0,0 +1,50 @@ +# Tutorials + +27 step-by-step guides covering every aspect of AI agent governance. + +## Foundations + +| # | Tutorial | What you'll learn | +|---|---------|------------------| +| 01 | [Policy Engine](01-policy-engine.md) | Core policy evaluation, rule authoring | +| 02 | [Trust & Identity](02-trust-and-identity.md) | Agent identity, trust tiers, verification | +| 03 | [Framework Integrations](03-framework-integrations.md) | Connect AGT to LangChain, CrewAI, OpenAI, etc. | +| 04 | [Audit & Compliance](04-audit-and-compliance.md) | Logging, evidence collection, compliance mapping | +| 05 | [Agent Reliability](05-agent-reliability.md) | SLOs, monitoring, graceful degradation | + +## Security + +| # | Tutorial | What you'll learn | +|---|---------|------------------| +| 06 | [Execution Sandboxing](06-execution-sandboxing.md) | Privilege rings, runtime isolation | +| 07 | [MCP Security Gateway](07-mcp-security-gateway.md) | Per-tool policy enforcement for MCP servers | +| 08 | [OPA / Rego / Cedar Policies](08-opa-rego-cedar-policies.md) | Policy engines comparison and integration | +| 09 | [Prompt Injection Detection](09-prompt-injection-detection.md) | Detecting and preventing prompt injection | +| 25 | [Security Hardening](25-security-hardening.md) | Production security best practices | +| 26 | [SBOM & Signing](26-sbom-and-signing.md) | Software bill of materials, artifact signing | +| 27 | [MCP Scan CLI](27-mcp-scan-cli.md) | Static analysis for MCP server security | + +## Advanced Patterns + +| # | Tutorial | What you'll learn | +|---|---------|------------------| +| 10 | [Plugin Marketplace](10-plugin-marketplace.md) | Marketplace governance, trust scoring | +| 11 | [Saga Orchestration](11-saga-orchestration.md) | Multi-step agent workflows with rollback | +| 12 | [Liability & Attribution](12-liability-and-attribution.md) | Decision tracing, blame assignment | +| 13 | [Observability & Tracing](13-observability-and-tracing.md) | Distributed tracing for agent systems | +| 14 | [Kill Switch & Rate Limiting](14-kill-switch-and-rate-limiting.md) | Emergency controls, throttling | +| 15 | [RL Training Governance](15-rl-training-governance.md) | Governing reinforcement learning agents | +| 16 | [Protocol Bridges](16-protocol-bridges.md) | Cross-protocol agent communication | +| 17 | [Advanced Trust](17-advanced-trust-and-behavior.md) | Behavioral analysis, reputation systems | +| 18 | [Compliance Verification](18-compliance-verification.md) | Automated compliance checks | +| 23 | [Delegation Chains](23-delegation-chains.md) | Agent-to-agent authorization | +| 24 | [Cost & Token Budgets](24-cost-and-token-budgets.md) | Resource governance | + +## SDK Guides + +| # | Tutorial | What you'll learn | +|---|---------|------------------| +| 19 | [.NET SDK](19-dotnet-sdk.md) | Agent governance in C# / .NET | +| 20 | [TypeScript SDK](20-typescript-sdk.md) | Agent governance in TypeScript | +| 21 | [Rust SDK](21-rust-sdk.md) | Agent governance in Rust | +| 22 | [Go SDK](22-go-sdk.md) | Agent governance in Go |