Skip to content

QUICKSTART.md

Latest commit

 

History

History
223 lines (160 loc) · 6.31 KB

QUICKSTART.md

File metadata and controls

223 lines (160 loc) · 6.31 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 agentmesh-runtime       # Execution supervisor + privilege rings
pip install agentmesh-marketplace      # Plugin lifecycle management
pip install agentmesh-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

Secure Error Handling

All CLI tools in the toolkit are hardened to prevent internal information disclosure. If a command fails in JSON mode, it returns a sanitized schema:

{
  "status": "error",
  "message": "An internal error occurred during verification",
  "type": "InternalError"
}

Known errors (e.g., "File not found") will include the specific error message, while unexpected system errors are masked to ensure security integrity.

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).