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 4, 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 4, 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.2-cp310-abi3-win_amd64.whl (4.1 MB view details)

Uploaded CPython 3.10+Windows x86-64

agent_guard_python-0.2.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.0 MB view details)

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

agent_guard_python-0.2.2-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.2-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.2-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.2-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.2-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 13889fd7c7d2bbd9c88127f2acb4e905de8907ff08d0bd9a7479a7dcc5689c0a
MD5 be931adb2bc87f075b8ec682c5904c29
BLAKE2b-256 3278e9c38827fb00b09b2184f5bcc686c17f3d3c6d3680ba43271d3e78e13231

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.2-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.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3e36c5c37687432a430df413e0f837be056896da239423ab0f67b15d2326bda1
MD5 393ea79fb7efbd5016b9baeca3655076
BLAKE2b-256 d2cb13cc060c972672b4fc05dbc3b96d11aec60132f2dd38dfc14f01e9854ef2

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.2-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.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0e1df044c645624b70b04b390abbe486da35367f186cea5ce89359f70cff0579
MD5 35957f3aa910fe7edfc9ded0f635edb8
BLAKE2b-256 e9bfa6423fc0709cc2ea1b604ab144e207e4a665f3f1627f132f874825a6e11f

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.2-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.2-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.2-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3500fb378a3b09f052928d3056f6171d1e041baeb40121d7668fe292adadcac8
MD5 8c44b47d7de56bc3ae83fc23bdc3b6c0
BLAKE2b-256 4c4554c634ec578cb0c7429eae7474042d6e90305f61a60a908f502661320835

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.2-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.2-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.2-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 4adf64f4c614250dae9ca3b09bd89c89de032ba1352d0e9cb59ae7ab3e275006
MD5 ea09f3f12cdd33bcc35a44a7c9dbbd0d
BLAKE2b-256 296a7ff936a93377c794c6865ef19c64f0bdb8baa834c59083e9fb7bb9cb25ce

See more details on using hashes here.

Provenance

The following attestation bundles were made for agent_guard_python-0.2.2-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

This release

0.2.2 This release

5 files

0.2.1

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