agentctl-sdk

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-sdk

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

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="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:

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("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.