One-line AgentSmack from Python, Jupyter, or any CI pipeline.

Install

Python 3.9+. Tested against 3.9 - 3.13 on Linux, macOS, and Windows. Ships a py.typed marker; mypy --strict clean.

What it gives you

• AgentSmack class

  Wraps POST /api/submissions + GET /api/submissions/[slug] with typed Pydantic models, header injection, and polling.

• Three submission modes

  Structured paste, raw text (any of JSON/YAML/Markdown), or a public URL — pass kwargs, a Pydantic model, or a TS-style dict.

• Offline pack verification

  Pure-Python Ed25519 + content-address re-derivation. Cross-language deterministic — a pack signed by Node verifies in Python and vice versa.

• CI/CD friendly

  `agentsmack analyze --wait --fail-on critical` returns non-zero so your pipeline fails the build on triggered probes. Same exit codes as the TS CLI.

• Deterministic

  `httpx.MockTransport` seam + injectable polling sleep. Pin the SDK in your replay tests — same input, same call sequence, byte-for-byte.

• Type-safe

  `py.typed` marker shipped. `mypy --strict` clean. Pydantic v2 models validate every wire boundary.

SDK quickstart

import os
from agentsmack import AgentSmack

agentsmack = AgentSmack(api_key=os.environ.get("AGENTSMACK_API_KEY"))
# (api_key is optional — anonymous submissions are allowed.)

result = agentsmack.analyze(
    system_prompt="You are a helpful assistant.",
    tool_list=[{"name": "search_web", "description": "Search the web"}],
    model="gpt-4o",
)
print(result.public_report_url)

# Block until honeypot + underground probes finish:
final = agentsmack.wait_for_completion(slug=result.public_slug)
print(final.probes)
# probes=ProbeCounts(honeypot=HoneypotProbeCounts(total=15, triggered=1, blocked=14), ...)

Fail the build on findings

analyze_and_wait(fail_on=...) raises a typed AgentSmackFindingsExceededError when any honeypot triggers or underground probe breaches at the chosen severity. Drop it into your CI step and the pipeline fails for you.

from agentsmack import AgentSmack, AgentSmackFindingsExceededError

agentsmack = AgentSmack()
try:
    submission, report = agentsmack.analyze_and_wait(
        system_prompt="...",
        wait=True,
        fail_on="critical",
    )
except AgentSmackFindingsExceededError as err:
    print(f"Triggered {err.triggered_count} probe(s) at {err.threshold}")
    raise SystemExit(1)

Offline pack verification

Every paid-tier submission produces a signed governance pack (content-addressed packId + Ed25519 signature). The Python verifier is cross-language deterministic — a pack signed by the TS SDK verifies in Python and vice versa, byte-for-byte.

from agentsmack import AgentSmack

verdict = AgentSmack.verify_pack_static(
    pack_json=open("pack.json").read(),
    signature_hex=open("pack.sig").read().strip(),
    public_key_hex=open("workspace.pub").read().strip(),
)

if not verdict.valid:
    raise RuntimeError(f"AgentSmack pack invalid: {verdict.reason}")

print(verdict.pack_id, verdict.bundle_digest)

CLI

Same package, same auth flow. agentsmack installs as a console script — perfect for shell scripts, Makefiles, and CI/CD steps. The exit-code matrix matches the TS CLI exactly so a pipeline switching languages keeps the same gating logic.

agentsmack login --api-key "$AGENTSMACK_API_KEY"

agentsmack analyze ./agent.json

agentsmack analyze ./agent.json \
  --wait --fail-on critical

cat .cursorrules | agentsmack analyze -

Verify a downloaded governance pack

agentsmack verify ./pack.json \
  --signature-file ./pack.sig \
  --public-key-file ./workspace.pub

Next

• /developers/sdk — same SDK in TypeScript / Node. Wire-compatible with this one.
• /developers/mcp — register AgentSmack as an MCP server in Claude Desktop / Cursor.
• /pricing — Pro-tier features include signed governance packs and the full honeypot battery.
• /samples — see what AgentSmack returns for common agent templates.