agent-guard-python

Python bindings for execution control at the agent side-effect boundary.

This package provides Python bindings for agent-guard, giving Python hosts a pre-execution decision layer before agent tool calls turn into shell commands or other side effects.

🚀 Quick Start (Python Adapters)

Status: The Python wrapper layer is a beta adapter surface. The clearest current proof point is still shell-first execution control, and Node remains the most mature integration path in the repository.

Integrate agent-guard into your existing LangChain tools with a policy gate in front of the original tool:

from agent_guard import Guard, wrap_langchain_tool

# 1. Initialize the Guard with your security policy
guard = Guard.from_yaml_file("policy.yaml")

# 2. Secure your existing tools
bash_tool = ShellTool() # Your original tool
secured_tool = wrap_langchain_tool(guard, bash_tool, agent_id="researcher")

# 3. Use the tool as normal - agent-guard handles the rest!
secured_tool.run("ls -la")

OpenAI-style handler wrapping is also available:

from agent_guard import Guard, wrap_openai_tool, AgentGuardDeniedError

guard = Guard.from_yaml_file("policy.yaml")

guarded_handler = wrap_openai_tool(
    guard,
    lambda input_data: {"ok": True, "query": input_data["query"]},
    tool="web_search",
    mode="check",
    trust_level="trusted",
)

try:
    print(guarded_handler({"query": "agent-guard"}))
except AgentGuardDeniedError as error:
    print("blocked", error.code)

✨ Features

  • 🛡️ Pre-execution policy decisions: Put allow/deny/ask checks in front of Python tool handlers.
  • 💻 Shell-first execution control: The strongest current execution path is still shell / Bash style tooling.
  • ⚠️ Typed adapter errors: Distinct deny, ask-required, and execution failure exceptions.
  • 📜 Signed receipts: Optional cryptographic proof of execution when you need deeper verification.
  • 🔏 Signed policy loading: Optional detached-signature verification for policy.yaml.
  • 📊 Auditing support: JSONL logs and metrics integration for operator-visible outcomes.

Current boundary note:

  • non-shell tools are most often a check-style policy gate first
  • shell-style execution remains the clearest current enforcement proof point
  • Python is an active adapter surface, but still below the current Node path in maturity
  • Guard.execute() / Guard.run() use the SDK default sandbox selection, or accept an explicit backend= keyword ("none", "linux-seccomp", "linux-landlock", "macos-seatbelt", "windows-job-object", "windows-appcontainer"); a backend that is not compiled into the module or not functional on the host resolves truthfully to "none", and an unknown name raises
  • to get real isolation through backend=, build the module with the matching feature forwarded, e.g. maturin develop --features extension-module,seccomp (requires libseccomp on Linux); the default build carries no sandbox feature
  • if the default sandbox diagnosis falls back to NoopSandbox, the policy gate still runs, but OS-level isolation is not equivalent

🔧 Installation

Version 0.2.0 is not on PyPI yet. Install it from a repository checkout (requires Python and a Rust toolchain):

python -m pip install ./crates/agent-guard-python

After the synchronized release, the distribution name will be agent-guard-python; the import name remains agent_guard:

from agent_guard import Guard

For local development in this repository:

cd crates/agent-guard-python
maturin develop --features extension-module
pytest tests -v

📺 Demos

Check the examples/ directory for full usage scenarios:

  • demo_langchain.py: Comprehensive 3-line integration demo.
  • provenance_receipt.py: Cryptographic verification example.

Project links

Data verified by PyPI on Sep 2, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for xuebin100 from gravatar.com xuebin100

GitHub Statistics

Data verified by PyPI on Sep 2, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT

Requires

Python >=3.10

Tags

security sandbox policy agent audit

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

agent_guard_python-0.2.1-cp310-abi3-win_amd64.whl (4.1 MB view details)

Uploaded CPython 3.10+Windows x86-64

agent_guard_python-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.9 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

agent_guard_python-0.2.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.9 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

agent_guard_python-0.2.1-cp310-abi3-macosx_11_0_arm64.whl (4.5 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

agent_guard_python-0.2.1-cp310-abi3-macosx_10_12_x86_64.whl (4.7 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file agent_guard_python-0.2.1-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.1-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 95add28efbfcc226f7cbfe6b5b6aed8a002d7c68f55b91f8da9b6f14d22ed20f
MD5 e7e7c14c09f89ae9954b0855eb0f9a3b
BLAKE2b-256 bac459c0e3819cacc3103744426aa2ce06d23b43851505d773665adb1ef9607d

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.1-cp310-abi3-win_amd64.whl:

Publisher: release.yml on XuebinMa/agent-guard

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agent_guard_python-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 45ee9723471028a26e1e0ca7691b9c4c35523e343c547e4e1ec7f20982069470
MD5 0cfaabd171daeb9bb312dd7e101fe998
BLAKE2b-256 d9d2f0425f7b372f09d91394880367f3ed37f7ca2f4fa1c49a6a373581800512

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on XuebinMa/agent-guard

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agent_guard_python-0.2.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ddb0e39bb90ff7f2a6e5635b9b5307970f1b90e2b4e6bc6e2ecc8b02bb44819d
MD5 3541e418109f4f4552cade52e2a18d47
BLAKE2b-256 cc8cd8195e57310073c1ce303382f868e52d3f0bf7bf0b84a3f603a851d638ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on XuebinMa/agent-guard

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agent_guard_python-0.2.1-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.1-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5d0b99485a4384744ecdda41682b035a6de02ceaf9479dadb8e3370924e23123
MD5 ca187e05b2ccea4ca4d7e820edce14af
BLAKE2b-256 a285b21b871bc408e2c5a26fc6046619533a2712fe0688995ca560fda440fdc4

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.1-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on XuebinMa/agent-guard

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agent_guard_python-0.2.1-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.1-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e959aeccca74029383bbd9a75cf8bad1c792a2037bd026e7de0bdca400a85c29
MD5 a59cf666d2235ea932b28872e0acbcef
BLAKE2b-256 6405c2828d1a4a12cca14e6d6ef56f5e028ec3c10336811957b7307523b8c57d

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.1-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on XuebinMa/agent-guard

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.3

5 files

0.2.2

5 files

This release

0.2.1 This release

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page