agentctl-sdk 0.1.0

Official Python SDK for agentctl — sign, hash-chain, and govern every agent action. Zero dependencies.

agentctl (Python SDK)

Official Python SDK for agentctl — 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

pip install agentctl

Quickstart

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:

r = ac.record_action(agent_id="billing-bot", tool="email.send", target="[e-mail]")
# 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:

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

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("[e-mail]")},
    "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.