hdp-autogen

HDP (Human Delegation Provenance) middleware for AutoGen — attach a cryptographic audit trail to any multi-agent conversation with zero changes to your existing code.

Every speaker turn in an AutoGen GroupChat is recorded in a tamper-evident chain of Ed25519 signatures, verifiable offline with a single public key.

pip install hdp-autogen

Quick start

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from autogen import ConversableAgent, GroupChat, GroupChatManager
from hdp_autogen import HdpMiddleware, HdpPrincipal, ScopePolicy, verify_chain

# 1. Your signing key (store in a secrets manager, never in code)
private_key = Ed25519PrivateKey.generate()

# 2. Define what the human is authorising
scope = ScopePolicy(
    intent="Coordinate research agents to summarise recent papers",
    authorized_tools=["web_search", "file_reader"],
    max_hops=10,
)

# 3. Create the middleware
middleware = HdpMiddleware(
    signing_key=private_key.private_bytes_raw(),
    session_id="research-2026-q1",
    principal=HdpPrincipal(id="researcher@lab.edu", id_type="email"),
    scope=scope,
)

# 4. Build your agents as normal
researcher = ConversableAgent("researcher", ...)
reviewer = ConversableAgent("reviewer", ...)
groupchat = GroupChat(agents=[researcher, reviewer], messages=[])
manager = GroupChatManager(groupchat=groupchat, ...)

# 5. Attach HDP — one line, zero agent changes
middleware.configure(manager)
manager.run_chat(messages=[{"role": "user", "content": "Summarise recent LLM papers"}])

# 6. Verify the delegation chain offline
result = verify_chain(middleware.export_token(), private_key.public_key())
print(result.valid, result.hop_count, result.violations)

Five design considerations

API reference

HdpMiddleware

HdpMiddleware(
    signing_key: bytes,          # Ed25519 private key (raw 32 bytes)
    session_id: str,             # unique ID for this conversation
    principal: HdpPrincipal,     # the human delegating authority
    scope: ScopePolicy,          # what is authorised
    key_id: str = "default",     # label stored in the token header
    expires_in_ms: int = 86400000,
    strict: bool = False,        # Deprecated; True raises ValueError at construction
)

verify_chain(token, public_key)

result = verify_chain(token_dict, public_key)  # Ed25519PublicKey or raw bytes
result.valid        # bool
result.hop_count    # int
result.violations   # list[str]
result.hop_results  # list[HopVerification]
result.recorded_after_period  # list[int] of hop seq values at or after expires_at

HDP tokens are records and cannot gate actions. authorized_tools records a declaration and does not authorize or block tool use. Expiry does not affect valid. The strict option remains for compatibility; setting it to True raises ValueError during construction. HDPScopeViolationError remains importable but is deprecated and never raised.

ScopePolicy

ScopePolicy(
    intent: str,
    data_classification: str = "internal",   # "public" | "internal" | "confidential" | "restricted"
    network_egress: bool = True,
    persistence: bool = False,
    authorized_tools: list[str] | None = None,
    authorized_resources: list[str] | None = None,
    max_hops: int | None = None,
)

Record-only behavior

Out-of-scope tool calls are recorded in the signed chain and the message continues through AutoGen. strict=True is retained for compatibility and raises ValueError during construction. The deprecated HDPScopeViolationError remains importable but is never raised.

After a session, inspect recorded tool calls in the token:

token = middleware.export_token()
for hop in token["delegation_chain"]:
    if hop.get("violation"):
        print(f"Hop {hop['seq']}: {hop['violation']}")

Cross-language compatibility

Python and TypeScript HDP tokens use the same wire format (RFC 8785 canonical JSON + Ed25519). A token issued by hdp-autogen (Python) can be verified by @helixar_ai/hdp (TypeScript) and vice versa — useful in mixed environments where some agents run in Python and others in Node.js.

# Python: export token
token_json = middleware.export_token_json()
# → pass to TypeScript service via API, message queue, etc.

// TypeScript: verify a token issued by Python
import { verifyChain } from "@helixar_ai/hdp";
const result = verifyChain(JSON.parse(tokenJson), publicKey);

Releasing

Published to PyPI via GitHub Actions when a matching tag is pushed:

git tag python/hdp-autogen/v0.2.0 && git push origin python/hdp-autogen/v0.2.0

Pipeline: test-hdp-autogen → vet-hdp-autogen (ReleaseGuard) → publish-hdp-autogen

Spec

This package follows draft-helixar-hdp-agentic-delegation-03 (latest revision).

License

Apache License 2.0 — Helixar Limited