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 6, 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:
Latest release

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

Uploaded CPython 3.10+Windows x86-64

agent_guard_python-0.2.3-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.3-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.3-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.3-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.3-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for agent_guard_python-0.2.3-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 b0c404d27fb674d0c6b5b69000bf36c989bf2b4594f97db5c271242cfe169eb2
MD5 05abc0747853e61899ffdaa7eeda4169
BLAKE2b-256 52c79b71d69a1abc5eb3fb464bea2ea0875756c90769886052e2c7ad18087ae4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_guard_python-0.2.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 cff97240f3de351fe6a416ddb92e1e1397a27ae90dff3d2175fe36f6be9fbc04
MD5 4ba92b4b6997121a004a77fd473b1a34
BLAKE2b-256 f7f4c6a19cb27ccb9f870ef5a93acf242496e3f71ac39aafff0304e75f926d61

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_guard_python-0.2.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 29754b8208b0ee396d810e91973e417a2afce39a610118e5a998b0e3915fe1c8
MD5 deb7e769c1366cb6b3c662dfd421bd13
BLAKE2b-256 f882e2875e1258c9f0a4edded4b37b821ff1257f51ea5e586ce4de27f4197675

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_guard_python-0.2.3-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8197605af42fa869baf5e87123fa6435e2f3ad3371c4541ca1b7723f9777ba5b
MD5 7b3aa4f8bebb4cc14899628ef3efe7fd
BLAKE2b-256 bc3b278ad22cb9616d9b2591abe68b1b9a1f84d37945616fc4a8f0078b1a047a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agent_guard_python-0.2.3-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 8868628361a59714fbf39eb68a00ad8f2013f7cbad2541986cae9a4dd3503eee
MD5 7fa3a1ee04af2b28f4fbf52ea03c3c67
BLAKE2b-256 1bd4acfb4aac59ed66d9297e78246812ee632c4e3beb1e7d8be37668e317339b

See more details on using hashes here.

Provenance

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

This release

0.2.3 This release

5 files

0.2.2

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