Skip to content

QUICKSTART.md

Latest commit

 

History

History
209 lines (150 loc) · 5.86 KB

QUICKSTART.md

File metadata and controls

209 lines (150 loc) · 5.86 KB

🚀 10-Minute Quick Start Guide

Get from zero to governed AI agents in under 10 minutes.

Prerequisites: Python 3.10+ / Node.js 18+ / .NET 8.0+ (any one or more).

Architecture Overview

The governance layer intercepts every agent action before execution:

graph LR
    A[AI Agent] -->|Tool Call| B{Governance Layer}
    B -->|Policy Check| C{PolicyEngine}
    C -->|Allowed| D[Execute Tool]
    C -->|Blocked| E[Security Block]
    D --> F[Audit Log]
    E --> F
    F --> G[OTEL / Structured Logs]
Loading

1. Installation

Install the governance toolkit:

pip install agent-governance-toolkit[full]

Or install individual packages:

pip install agent-os-kernel        # Policy enforcement + framework integrations
pip install agentmesh-platform     # Zero-trust identity + trust cards
pip install agent-governance-toolkit    # OWASP ASI verification + integrity CLI
pip install agent-sre              # SLOs, error budgets, chaos testing
pip install agent-runtime          # Execution supervisor + privilege rings
pip install agent-marketplace      # Plugin lifecycle management
pip install agent-lightning        # RL training governance

TypeScript / Node.js

npm install @agentmesh/sdk

.NET

dotnet add package Microsoft.AgentGovernance

2. Verify Your Installation

Run the included verification script:

python scripts/check_gov.py

Or use the governance CLI directly:

agent-governance verify
agent-governance verify --badge

3. Your First Governed Agent

Create a file called governed_agent.py:

from agent_os.policy import PolicyEngine, CapabilityModel, PolicyScope

# Define what your agent is allowed to do
capabilities = CapabilityModel(
    allowed_tools=["web_search", "read_file", "send_email"],
    blocked_tools=["execute_code", "delete_file"],
    blocked_patterns=[r"\b\d{3}-\d{2}-\d{4}\b"],  # Block SSN patterns
    require_human_approval=True,
    max_tool_calls=10,
)

# Create a policy engine
engine = PolicyEngine(capabilities=capabilities)

# Every agent action goes through the policy engine
result = engine.evaluate(action="web_search", input_text="latest AI news")
print(f"Action allowed: {result.allowed}")
print(f"Reason: {result.reason}")

# This will be blocked
result = engine.evaluate(action="delete_file", input_text="/etc/passwd")
print(f"Action allowed: {result.allowed}")  # False
print(f"Reason: {result.reason}")           # "Tool 'delete_file' is blocked"

Run it:

python governed_agent.py

Your First Governed Agent — TypeScript

Create a file called governed_agent.ts:

import { PolicyEngine, AgentIdentity, AuditLogger } from "@agentmesh/sdk";

const identity = AgentIdentity.generate("my-agent", ["web_search", "read_file"]);

const engine = new PolicyEngine([
  { action: "web_search", effect: "allow" },
  { action: "delete_file", effect: "deny" },
]);

console.log(engine.evaluate("web_search"));  // "allow"
console.log(engine.evaluate("delete_file")); // "deny"

Your First Governed Agent — .NET

Create a file called GovernedAgent.cs:

using AgentGovernance;
using AgentGovernance.Policy;

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

var result = kernel.EvaluateToolCall("did:mesh:agent-1", "web_search", new() { ["query"] = "AI news" });
Console.WriteLine($"Allowed: {result.Allowed}");  // True (if policy permits)

result = kernel.EvaluateToolCall("did:mesh:agent-1", "delete_file", new() { ["path"] = "/etc/passwd" });
Console.WriteLine($"Allowed: {result.Allowed}");  // False

4. Wrap an Existing Framework

The toolkit integrates with all major agent frameworks. Here's a LangChain example:

from agent_os import KernelSpace
from agent_os.policy import CapabilityModel

# Initialize with governance
kernel = KernelSpace(
    capabilities=CapabilityModel(
        allowed_tools=["web_search", "calculator"],
        max_tool_calls=5,
    )
)

# Wrap your LangChain agent — every tool call is now governed
governed_agent = kernel.wrap(your_langchain_agent)

Supported frameworks: LangChain, OpenAI Agents SDK, AutoGen, CrewAI, Google ADK, Semantic Kernel, LlamaIndex, Anthropic, Mistral, Gemini, and more.

5. Check OWASP ASI 2026 Coverage

Verify your deployment covers the OWASP Agentic Security Threats:

# Text summary
agent-governance verify

# JSON for CI/CD pipelines
agent-governance verify --json

# Badge for your README
agent-governance verify --badge

6. Verify Module Integrity

Ensure no governance modules have been tampered with:

# Generate a baseline integrity manifest
agent-governance integrity --generate integrity.json

# Verify against the manifest later
agent-governance integrity --manifest integrity.json

Next Steps

What Where
Full API reference (Python) packages/agent-os/README.md
TypeScript SDK docs packages/agent-mesh/sdks/typescript/README.md
.NET SDK docs packages/agent-governance-dotnet/README.md
OWASP coverage map docs/OWASP-COMPLIANCE.md
Framework integrations packages/agent-os/src/agent_os/integrations/
Example applications packages/agent-os/examples/
Contributing CONTRIBUTING.md
Changelog CHANGELOG.md

Based on the initial quickstart contribution by @davidequarracino (#106, #108).