agenticrail

agenticrail

AgenticRail Python SDK — deterministic sequence enforcement for AI agents.

Gate every step of your agent workflow before it executes. Cryptographic receipts. Zero enforcement failures.

pip install agenticrail

---

What it does

AgenticRail sits beneath your agent and enforces that steps run in the right order, with no skips, no replays, and no re-entry after a sequence is sealed. Every decision — ALLOW, DENY, or HALT — produces a cryptographically signed receipt stored at the edge.

Three verdicts:

• ALLOW — step is clear, your agent code executes
• DENY — enforcement violation (wrong order, replay, sealed), execution blocked
• HALT — hard stop (injection attempt, poison payload detected), execution blocked

---

Install

# Core client only
pip install agenticrail

# With LangGraph support
pip install "agenticrail[langgraph]"

# With CrewAI support
pip install "agenticrail[crewai]"

# Everything
pip install "agenticrail[all]"

---

Quick start — any framework

You do not need a key. There is nothing to sign up for.

Since 0.3.0 the client sends no credential unless you give it one, and the gate serves unrecognised callers on its public demo lane: the call runs, the receipt is real and signed, and the response tells you which lane you are on via lane, lane_reason and lane_notice.

The trade is that a demo-lane sequence is prefixed demo-, is rate limited to 300 requests/minute, and its report is readable by anyone holding the sequence id at report.agenticrail.nz/report. So evaluate freely, and do not put anything private in attestation until you are on a key of your own.

DEMO-AGENTICRAIL-PUBLIC-2026 is that lane's real, public key if you would rather name it explicitly. It is not a placeholder.

Production keys look different — prefix.secret, with a dot. Pass anything else, including an unset environment variable, and you are not turned away: the call runs on the demo lane and says so. Only a real key presented wrongly is refused. For a production key: hello@agenticrail.nz

What the demo key can do, and what is public

It is a real key, not a sandbox. Your own step names, your own order, your own inputs, every action type, signed receipts, full chain verification. The only differences from a production key are the demo- prefix on your sequence ids, the 300 req/min limit, and a shared model_id.

inputs and attestation are treated differently. This is the one thing to read before pointing the demo key at real work.

inputs is for the payload. A third party can prove your sequence ran in order and was not tampered with, and still learn nothing about what was in it.

attestation is for the evidence you want a reader to see — {"aml_check": "passed", "approvals": ["alice@co.com"]} — so it appears verbatim in the report. That is the design, not a leak, but it means anything you put in attestation on a demo sequence is world-readable.

And any demo- sequence can be read by anyone who knows or guesses its id, with no key at all. So kyc_check → credit_decision → disburse_funds tells a reader your process even though it tells them nothing about the customer.

Use a random sequence id per run. If the step names or the attestation contents are sensitive, that is the point to move to a production key — hello@agenticrail.nz.

Give every run a fresh sequence_id. Sealing is permanent and by design: once a sequence reaches its last step it can never be reopened. A fixed id therefore works exactly once — and on the shared demo key that id is shared with every other user, so the second person to run it gets RailDenied: SEALED_SEQUENCE. That is the gate working, not a bug.

import uuid

from agenticrail import RailClient

# No key needed. With no argument the client uses $AGENTICRAIL_API_KEY if
# set, and otherwise sends no credential at all -- the gate answers on its
# public demo lane and every decision carries `lane` so you know where you are.
client = RailClient()

# Silences the startup warning by naming the same lane explicitly:
#   client = RailClient(api_key=DEMO_API_KEY)

# RailSequence sends step_order on every call — the gate reads it from each payload
seq = client.sequence(
    sequence_id=f"my-agent-run-{uuid.uuid4().hex[:8]}",
    step_order=["verify_identity", "assess_risk", "execute_transfer", "audit_ledger"],
)

seq.next("verify_identity")    # → ALLOW
seq.next("assess_risk")        # → ALLOW
seq.next("execute_transfer")   # → ALLOW
seq.next("audit_ledger")       # → ALLOW (seals sequence)

# Any out-of-order, replay, or post-seal call raises RailDenied
seq.next("verify_identity")    # → raises RailDenied: SEALED_SEQUENCE

Get a production API key at agenticrail.nz.

---

LangGraph integration

Wrap each node at add_node time. Uses thread_id from LangGraph config as the sequence_id — each graph invocation is isolated.

from langgraph.graph import StateGraph, END
from agenticrail import RailClient
from agenticrail.integrations.langgraph import LangGraphRail

client = RailClient()  # $AGENTICRAIL_API_KEY, else the public demo lane
rail = LangGraphRail(
    client,
    step_order=["research", "analyze", "write_report", "review"],
)

builder = StateGraph(AgentState)

# Wrap each node — gate fires before node execution
builder.add_node("research",     rail.wrap("research",     research_fn))
builder.add_node("analyze",      rail.wrap("analyze",      analyze_fn))
builder.add_node("write_report", rail.wrap("write_report", write_report_fn))
builder.add_node("review",       rail.wrap("review",       review_fn))

builder.set_entry_point("research")
builder.add_edge("research",     "analyze")
builder.add_edge("analyze",      "write_report")
builder.add_edge("write_report", "review")
builder.add_edge("review",       END)

graph = builder.compile()

# thread_id → sequence_id: each invocation is independently tracked and verifiable
result = graph.invoke(
    {"query": "EU AI Act compliance checklist"},
    config={"configurable": {"thread_id": "run-2026-001"}},
)

What happens on DENY or HALT: rail.wrap() raises RailDenied inside the node. LangGraph catches unhandled node exceptions and halts graph execution. No subsequent nodes run.

Concurrent runs: Each thread_id is a separate sequence. Concurrent graph invocations with different thread IDs do not interfere — the gate tracks them independently via Durable Objects.

---

CrewAI integration

Use guard.kickoff() instead of crew.kickoff(). Step[0] is gated before the crew starts; subsequent steps are gated via a task callback injected between tasks.

from crewai import Crew
from agenticrail import RailClient
from agenticrail.integrations.crewai import CrewRailGuard

client = RailClient()  # $AGENTICRAIL_API_KEY, else the public demo lane
guard = CrewRailGuard(
    client,
    step_order=["research_task", "analysis_task", "write_task"],
)

crew = Crew(
    agents=[researcher, analyst, writer],
    tasks=[research_task, analysis_task, write_task],
)

# Drop-in replacement for crew.kickoff()
# Each call generates a fresh sequence_id — each run is independently tracked
result = guard.kickoff(crew, inputs={"topic": "AI governance"})

Note on blocking: CrewAI's task_callback fires synchronously between tasks, so the gate can block task N before task N starts. However, if CrewAI swallows exceptions in callbacks, a denied task may still execute. In that case, guard.kickoff() raises RailDenied after the crew finishes, preserving the denial in the audit trail.

For hard blocking (guaranteed pre-execution), use guard.gate() in a custom orchestration loop:

guard.reset()
for step, task_fn in zip(STEP_ORDER, task_functions):
    guard.gate(step)   # raises RailDenied immediately on DENY
    task_fn()

---

API reference

RailClient

client = RailClient(
    api_key=None,        # Optional. Omit it and the gate answers on the
                         # public demo lane, labelled in every response.
    model_id="agent",    # Optional. Identifies your agent in receipts.
    base_url=None,       # Optional. Defaults to api.agenticrail.nz/v1/evaluate.
    timeout=10,          # Optional. Request timeout in seconds.
)

client.evaluate(sequence_id, step, *, ...)

decision = client.evaluate(
    sequence_id=f"my-run-{uuid.uuid4().hex[:8]}",  # fresh id per run
    step="verify_identity",
    action_type="CHECK_STATE",     # Optional. Default: CHECK_STATE.
    action="verify user identity", # Optional. Human-readable label.
    inputs={"user_id": "u123"},    # Optional. Metadata attached to receipt.
    step_order=[...],              # Required on every call — gate reads it from each payload.
    raise_on_deny=True,            # Optional. Default True.
)
# decision.decision  → "ALLOW" | "DENY" | "HALT"
# decision.allowed   → True if ALLOW
# decision.pack_id   → SHA-256 receipt hash
# decision.receipt   → full signed receipt dict
# decision.reasons   → list of reason codes on DENY/HALT

client.sequence(sequence_id, step_order)

Returns a RailSequence that tracks step_order state — call .next(step) for each step without managing step_order yourself.

RailDenied

try:
    seq.next("execute_transfer")
except RailDenied as e:
    print(e.decision)   # "DENY" or "HALT"
    print(e.reasons)    # ["SEQUENCE_VIOLATION"]
    print(e.pack_id)    # receipt hash for audit
    print(e.step)       # "execute_transfer"

LangGraphRail

rail = LangGraphRail(
    client,
    step_order=["step_a", "step_b", "step_c"],
    fallback_sequence_id=None,  # Used when thread_id not in config
)
wrapped_fn = rail.wrap("step_a", original_fn, action_type="CHECK_STATE")

CrewRailGuard

guard = CrewRailGuard(
    client,
    step_order=["task_1", "task_2", "task_3"],
    sequence_id=None,    # Optional. Auto-generated per kickoff() call if None.
    action_type="CHECK_STATE",
)
result = guard.kickoff(crew, inputs={...})
guard.gate("task_1")     # Explicit gate for custom loops
guard.reset()            # Reset state for a new run

---

Compliance reports

Every pack_id in a RailDecision is a verifiable receipt. Paste your sequence ID into the report generator or call it programmatically:

curl -X POST https://api.agenticrail.nz/v1/report \
  -H "Authorization: Bearer DEMO-AGENTICRAIL-PUBLIC-2026" \
  -H "Content-Type: application/json" \
  -d '{"sequence_id": "my-run-001", "format": "json"}'

Returns: chain proof (Ed25519 signature verification, offline-reproducible; legacy HMAC k1 verified server-side for pre-cutover receipts), enforcement log, AI-written compliance narrative.

Demo sequences (using DEMO-AGENTICRAIL-PUBLIC-2026) are verifiable at report.agenticrail.nz — no auth needed.

---

Action types

---

Links

• API docs: agenticrail.nz/docs
• Interactive demo: agenticrail.nz/demo
• Compliance matrix: agenticrail.nz/compliance — what this actually provides, and what it does not
• Verify a sequence: report.agenticrail.nz

---

TUARA KURI LIMITED — trading as AgenticRail. Hokianga, New Zealand.