Metadata-Version: 2.4
Name: agentguard-tech
Version: 0.11.3
Summary: AgentGuard Python compatibility SDK for HTTP policy evaluation and integration adapters.
Author-email: The Bot Club Pty Ltd <hello@agentguard.tech>
License: Business Source License 1.1
Project-URL: Homepage, https://agentguard.tech
Project-URL: Documentation, https://agentguard.tech/docs/
Project-URL: Repository, https://github.com/thebotclub/agentguard-core
Project-URL: Issues, https://github.com/thebotclub/agentguard-core/issues
Project-URL: Limitations, https://agentguard.tech/trust/
Keywords: ai-agents,agent-security,policy-engine,openclaw,mcp,runtime-security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# agentguard-tech

Python compatibility SDK `0.11.3` for AgentGuard HTTP policy evaluation. This
distribution is maintained for truthful compatibility and security fixes; it is
not the normative v1 runtime contract and does not claim equivalent TypeScript
feature scope, executor-owned capability separation, or a compliance outcome.

[![PyPI](https://img.shields.io/pypi/v/agentguard-tech?color=38bdb0)](https://pypi.org/project/agentguard-tech/)
[![Python](https://img.shields.io/pypi/pyversions/agentguard-tech?color=38bdb0)](https://pypi.org/project/agentguard-tech/)
[![license](https://img.shields.io/badge/license-BSL%201.1-orange)](https://agentguard.tech/docs/#source)
[![homepage](https://img.shields.io/badge/site-agentguard.tech-38bdb0)](https://agentguard.tech)

The distribution name is `agentguard-tech`; Python imports use `agentguard`.
The TypeScript package is an independent release named
[`@the-bot-club/agentguard`](https://www.npmjs.com/package/@the-bot-club/agentguard).

## Install

```bash
pip install agentguard-tech
```

## Quick start

```python
from agentguard import AgentGuard

guard = AgentGuard(api_key="ag_live_...")
decision = guard.evaluate(tool="shell_exec", params={"cmd": "rm -rf /"})
# → {"result": "block", "riskScore": 95, "reason": "...", "durationMs": 1.2}
```

`evaluate()` returns the camelCase keys that `POST /api/v1/evaluate` returns:

| Key | Value |
|-----|-------|
| `result` | `"allow"`, `"block"`, `"monitor"` or `"require_approval"` |
| `riskScore` | int, 0–1000 |
| `reason` | str |
| `durationMs` | float |
| `matchedRuleId` | str, present only when a rule matched |

A kill-switch block additionally carries `killSwitchActive: True`. Other optional
fields the API may add on a block or `require_approval` include `agentId`,
`approvalId`, `approvalUrl`, `suggestion`, `docs`, `alternatives`, `notice`,
`warnings` and `pii` — treat anything beyond the five keys above as optional.

With `local_eval=True` and a cached policy bundle, `evaluate()` runs in process
and returns those same keys, so callers never have to branch on which path
produced a decision.

## Policy templates

`list_templates()` returns the template ids this deployment actually serves;
`get_template(name)` and `apply_template(name)` take an id from that list. The
set of ids is a property of the deployment, not of this package.

## OpenClaw compatibility hook

`OpenClawGuard` is a Python-side HTTP adapter for a structural
`before_tool_call` hook. Strict mode is required and returns a block decision
on HTTP failure. `strict=False` is a hard startup error. The hook can be
disabled or bypassed and owns no raw capability under a separate identity, so
it is compatibility telemetry only.

```python
from agentguard.integrations.openclaw import openclaw_guard

guard = openclaw_guard(
    api_key=os.environ["AGENTGUARD_API_KEY"],
    agent_id="ops-dispatch-1",
    strict=True,
)
```

OpenClaw-provided session, run, and tool-call IDs are correlation data only.
Other integration modules in this distribution are compatibility adapters; their
presence is not evidence of runtime coverage or equivalent v1 feature scope.

## Telemetry

Telemetry is **opt-in and off by default**. Nothing is sent unless you construct
the client with `telemetry=True`:

```python
guard = AgentGuard(api_key=key, telemetry=True)   # opt in
guard = AgentGuard(api_key=key)                   # default: nothing sent
```

When you opt in, the SDK sends **one** anonymous ping to
`POST {base_url}/api/v1/telemetry` per client instance, on the first
`evaluate()` call. The payload is exactly four fields:

| Field | Value |
|-------|-------|
| `sdk_version` | this distribution's version, e.g. `0.11.3` |
| `language` | `python` |
| `node_version` | the Python version, e.g. `python/3.12.14` |
| `os_platform` | `platform.system().lower()`, e.g. `linux` |

No API key, tool name, parameters, policy, decision, hostname, or IP-derived
identifier is included, and the ping is fire-and-forget on a daemon thread — it
never raises and never delays an evaluation.

Setting the environment variable `AGENTGUARD_NO_TELEMETRY=1` force-disables the
ping even when `telemetry=True` is passed.

This is separate from your own audit trail: in `local_eval=True` mode the client
batches decision records to `POST /api/v1/audit` under your API key. That is your
tenant's data, not usage telemetry, and it is not controlled by this setting.

## Documentation

- Website — [agentguard.tech](https://agentguard.tech)
- Docs — [agentguard.tech/docs/](https://agentguard.tech/docs/)
- OpenClaw integration — [agentguard.tech/openclaw/](https://agentguard.tech/openclaw/)
- Source — [agentguard.tech/docs/#source](https://agentguard.tech/docs/#source)
- Support — [hani@thebot.club](mailto:hani@thebot.club)

## Licence

Business Source License 1.1. The `LICENSE` file shipped in this distribution is
authoritative.
© 2026 The Bot Club Pty Ltd (ABN 99 695 980 226).
