Metadata-Version: 2.4
Name: agentctl-sdk
Version: 0.1.1
Summary: Official Python SDK for agentctl — sign, hash-chain, and govern every agent action. Zero dependencies.
Author-email: Zeron <hello@zeron.one>
License: Apache-2.0
Project-URL: Homepage, https://openagp.io
Project-URL: Specification, https://github.com/openagp/spec
Keywords: agentctl,openagp,ai-agents,governance,audit,tamper-evident,ledger
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: System :: Logging
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# agentctl (Python SDK)

Official **Python SDK** for [agentctl](https://agentctl.io) — sign, hash-chain, and govern
every action your AI agents take. The event format is the open **AGP** spec, so what you
emit is portable and independently verifiable. Standard library only, no dependencies.

## Install

```bash
pip install agentctl-sdk
```

> The PyPI package is **`agentctl-sdk`**; the import name is `agentctl`.
> (Do not `pip install agentctl` — that is an unrelated package.)

## Quickstart

```python
import os
from agentctl import Agentctl

ac = Agentctl("https://app.agentctl.io", os.environ["AGENTCTL_TOKEN"], default_vendor="openai")

ac.record_action(
    agent_id="billing-bot",
    tool="stripe.refund",
    target="cus_9021",
    decision="allowed",
)
```

Every call returns the signed, hash-chained record:

```python
r = ac.record_action(agent_id="billing-bot", tool="email.send", target="x@acme.com")
# r["event_id"], r["prev_hash"], r["this_hash"], r["scf_controls"], r.get("duplicate")
```

## Runs (lineage)

Group an agent's steps into one trace — events chain parent → child automatically:

```python
run = ac.run()  # or ac.run("trc_my_id")
run.record_action(agent_id="research-agent", type="session_open")
run.record_action(agent_id="research-agent", tool="web.search", target="market sizing")
run.record_action(agent_id="research-agent", tool="snowflake.query", target="prod.orders")
run.record_action(agent_id="research-agent", type="session_close")
```

## Full event

```python
from agentctl import hash_principal

ac.record({
    "actor": {"agent_id": "claude-code", "vendor": "anthropic", "model": "claude-opus-4-8",
              "framework": "claude-code", "human_principal": hash_principal("user@acme.com")},
    "action": {"type": "tool_call", "tool_name": "bash", "target_resource": "cat .env"},
    "policy": {"decision": "blocked", "rule_id": "rule_secret_file"},
})
```

`hash_principal()` SHA-256s a user id so you never store it in plaintext.

## API

- `Agentctl(base_url, token, *, default_vendor="custom", timeout=10.0)`
- `.record(event) -> dict`
- `.record_action(agent_id, *, tool=, target=, decision=, type=, vendor=, model=, framework=, principal=) -> dict`
- `.run(trace_id=None) -> Run` with `.record()` / `.record_action()` (auto lineage)
- `hash_principal(user_id) -> str`

Apache-2.0.
