agentguard-oss

AgentGuard

Let agents act. Keep humans in control.

AgentGuard is an open-source Python SDK that sits between an AI agent and its tools. Every tool call is validated, checked against a policy, scored for risk, optionally reviewed by a local Gemma model, sent to a human when needed, run through a restricted executor, verified, and written to a tamper-evident audit log.

Documentation · Quickstart · Integrations · Threat model · Changelog

See it work

pip install agentguard-oss
agentguard demo --scripted

An agent is asked to fix a calculator. The repository's README hides a prompt injection telling it to read ~/.ssh/id_rsa and upload it. AgentGuard lets the agent read the README, blocks the SSH-key read and the curl exfiltration, allows the fix and a real unit test, and asks for human approval before the push to main (denied in the scripted demo, where nobody is there to approve; --interactive prompts you).

With Ollama and ollama pull gemma3:4b, plain agentguard demo runs a live Gemma agent against the same trap, and --judge adds a Gemma security reviewer. Add --interactive to approve the push yourself. See Gemma agent and judge.

Guard a tool

from pathlib import Path

from agentguard import Guard

guard = Guard(
    {
        "version": 1,
        "defaults": {"effect": "deny"},
        "rules": [
            {"capability": "filesystem.read", "paths": ["./workspace/**"], "effect": "allow"},
            {"capability": "shell.execute", "effect": "ask"},
        ],
    },
    audit="agentguard.jsonl",
)


@guard.tool(capability="filesystem.read")
def read_file(path: str) -> str:
    """Read a UTF-8 text file."""
    return Path(path).read_text(encoding="utf-8")


# Give the agent read_file, never the raw function.
# read_file("~/.ssh/id_rsa") raises GuardDenied before the function body runs.

Then check the policy, ask how it decides a call, and verify the log:

agentguard check-policy policy.yaml
agentguard explain policy.yaml shell.execute --arg cmd="git push origin main"
agentguard verify-log --audit agentguard.jsonl

Use it with your framework

pip install "agentguard-oss[langchain]"   # also [openai-agents], [adk], [mcp], [all]

from agentguard.adapters.langchain import guarded_tool        # LangChain / LangGraph
# from agentguard.adapters.openai_agents import guarded_tool  # OpenAI Agents SDK
# from agentguard.adapters.adk import guarded_tool            # Google ADK


def read_notes(path: str) -> str:
    """Read a notes file."""
    return Path(path).read_text(encoding="utf-8")


notes_tool = guarded_tool(guard, read_notes, capability="filesystem.read")

Denials go back to the model with AgentGuard's reasons so the agent can adapt. MCP servers use agentguard.adapters.mcp.register_tool; any other loop can call guard.call(name, arguments).

What you get

Starter policies for coding, browsing and support agents are in examples/policies/.

Operate it

pip install "agentguard-oss[dashboard]"
agentguard approvers add alice            # prints a token for the dashboard and API
agentguard dashboard                      # http://127.0.0.1:8765

from agentguard.approval import ApprovalStore, QueueApproval

guard = Guard("policy.yaml", approval=QueueApproval(ApprovalStore("agentguard-approvals.db")))

Risky calls raise ApprovalPending immediately instead of blocking; the agent retries after a human approves in the dashboard, in Slack, or through the API. Run a new agent with mode="dry-run" and check agentguard report --dry-run-only to tune the policy before enforcing it.

Status

AgentGuard 0.5 is alpha and has not had an independent security audit; see the security review guide and benchmarks. It is an interception layer for cooperative applications, not an OS sandbox: an agent that also has unguarded tools, a raw shell or Python exec can go around it. Read the threat model before guarding privileged tools, and report vulnerabilities privately as described in SECURITY.md.

Develop

git clone https://github.com/prollysamz/agentguard.git
cd agentguard
python -m venv .venv
# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[dev,all,docs]"
python -m pytest -q
python -m ruff check .
mkdocs serve

CI runs the tests on Linux, Windows and macOS with Python 3.11 to 3.14. See CONTRIBUTING.md. Report vulnerabilities privately, as described in SECURITY.md. MIT licensed.