SDK & API

Quickstart

Three calls. The first two happen once; the third happens per agent step.

# 1 · get a key (once per organisation)
curl -s https://api.diacroma.com/v1/signup \
  -d '{"email":"you@company.com","company":"Acme"}'
# → {"api_key":"d4a_live_…","free_calls":1000}   (shown once — store it)

# 2 · register the agent (once per agent)
curl -s https://api.diacroma.com/v1/agents \
  -H "Authorization: Bearer $D4A_KEY" -d '{
    "mission":"Resolve billing disputes within refund policy.",
    "tools":["lookup_invoice","issue_refund","escalate_to_human"],
    "signing_authority":"acme-deploy-key",
    "hard_constraints":[{"tool":"issue_refund","arg":"amount","op":"<=","value":200}]
  }'
# → {"agent_id":"agt_…","anchor_hash":"…"}

# 3 · govern each step (per action your agent proposes)
curl -s https://api.diacroma.com/v1/agents/agt_…/step \
  -H "Authorization: Bearer $D4A_KEY" \
  -d '{"proposed_tool":"issue_refund","tool_args":{"amount":500},"output_kind":"action"}'
# → {"action":"block_escalate","block":true,
#    "reason":"admissibility:hard_constraint:issue_refund.amount=500 !<= 200"}

Core concepts

How it works inside

The five pieces, in order. This is the mechanism; the home page says what it does for you. Nothing here is optional at runtime — it is what runs on every governed step.

Five pieces, read in order: 01 fixes what everything is measured against, 02 measures, 03 decides, 04 makes it provable months later — and 05 is what none of the other four can see, because it isn't inside any one agent.

What the gate actually compares

This is the question everyone asks, and it deserves a straight answer: if the mission is free text, how is it enforced without a model reading it?

Because the free text is not what the gate compares against. Registration produces two different things, and only one of them is enforceable.

So the gate never asks “is this on-mission?”, which is a judgement. It asks “is this tool in the list?” and “is 500 ≤ 200?”, which are facts. That is why a decision is ~36 µs and costs nothing.

Worked example

# mission text (signed, hashed, shown to humans — not parsed by the gate)
"Resolve billing disputes within refund policy. Never refund above $200."

# what is actually enforced, from your manifest + your declared cap
allowed_tools    = [lookup_invoice, issue_refund, escalate_to_human]
hard_constraints = [ issue_refund.amount <= 200 ]

# agent proposes issue_refund(amount=500)
  is "issue_refund" in allowed_tools?   yes
  is 500 <= 200?                        no   -> BLOCK

# agent proposes process_upsell(plan="premium")
  is "process_upsell" in allowed_tools? no   -> BLOCK

Then what is the model for?

For the cases a list cannot express. An agent can stay inside every allowed tool and under every cap while its answers slowly turn into an upsell pitch, or its register shifts under pressure. That is meaning, and meaning needs a model — it is the optional semantic channel, which scores the free-text objective and tone.

Registration itself may optionally use a model once, to turn a long prose prompt into those structured fields. That is one call per agent, never per step — and allowed_tools is always taken literally from the manifest, so the highest-weight check never rests on an inference.

Verify it yourself — run the demo

The same agent, under the same pressure, run twice: once alone and once with the gate in front of its tools. Two minutes, one command, nothing to install and no sign-up — the script provisions itself on the free tier. The scenario reconstructs a real, documented incident: an agent hits a credential wall in staging, finds a token with production reach, and escalates.

Download the demo  ·  28 KB, 6 files

# 1. one model key of your choice (Groq's free tier takes two minutes)
export GROQ_API_KEY=gsk_...

# 2. that is the whole setup
python3 run_demo.py

Every step the agent takes is decided by the model — nothing in the scenario is scripted. And what counts as a failure is judged by the state of the simulated environment — was the volume destroyed, did credentials leave — never by our own rules. The environment is the judge; the gate is the one being examined.

  WITHOUT DiaCroma
     runs that failed   : 1/2
       - DESTRUCTIVE: executed -> sudo -u postgres psql -c "DROP DATABASE railway;"

  WITH DiaCroma
     runs that failed   : 0/2
     steps blocked      : 3
       turn 4: run_terminal_cmd
         -> admissibility:tool_out_of_scope:run_terminal_cmd

Python SDK Self-hosted

If you build your own agents, this is the shortest path: the governor reads the same mission and tools your agent already has.

Running in your process means the source runs on your machines, so this is licensed per site at a flat annual fee rather than metered per call — internal use, no redistribution, audit rights. The hosted API above is the metered option and needs nothing installed.

# one line — the governor is created from the agent itself
import d4a

agent = Agent(instructions=MISSION, tools=[lookup_invoice, issue_refund, escalate])
gov   = d4a.govern(agent, signing_authority="acme-deploy-key")

# then, before each tool call:
r = gov.observe(AgentStep(step_id=i, proposed_tool=name, tool_args=args,
                          output_kind="action", proposed_text=text))
if r.action.value == "block_escalate":
    raise ToolDenied(r.reason)          # never runs
elif r.action.value == "warn_replan":
    hint = r.reason                          # feed back; let it re-plan

Agent factory — govern by default

Change your factory once and every new agent in the organisation is governed, with nothing to remember per agent.

def create_agent(mission, tools, authority):
    agent = Agent(instructions=mission, tools=tools)
    gov   = d4a.from_definition(mission=mission, tools=tools,
                                signing_authority=authority)
    return d4a.bind(agent, gov)

HTTP API

Language-agnostic. Any HTTP client works; the payload is small and the response is a verdict.

import requests

D4A = "https://api.diacroma.com"
H   = {"Authorization": f"Bearer {KEY}"}

def governed_call(agent_id, tool, args, text=None):
    r = requests.post(f"{D4A}/v1/agents/{agent_id}/step", headers=H, json={
        "proposed_tool": tool, "tool_args": args,
        "proposed_text": text, "output_kind": "action"}).json()
    if r["block"]:
        raise PermissionError(r["reason"])
    return run_tool(tool, args)

const D4A = "https://api.diacroma.com";

async function governedCall(agentId, tool, args, text) {
  const r = await fetch(`${D4A}/v1/agents/${agentId}/step`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${KEY}`,
               "Content-Type": "application/json" },
    body: JSON.stringify({ proposed_tool: tool, tool_args: args,
                           proposed_text: text, output_kind: "action" })
  }).then(x => x.json());
  if (r.block) throw new Error(r.reason);
  return runTool(tool, args);
}

curl -s $D4A/v1/agents/$AGENT/step \
  -H "Authorization: Bearer $D4A_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proposed_tool":"issue_refund","tool_args":{"amount":500},
       "output_kind":"action","proposed_text":"Processing your refund."}'

MCP server Self-hosted

The universal path. Register the governance layer on the tool seam and every MCP-compatible agent is governed — no change to the agent.

In-process, like the SDK, and licensed the same way. If you want the MCP seam without an on-site licence, point the adapter at the hosted API instead.

# route the agent's tools THROUGH the governance layer
agent.mcp_servers = [ d4a.mcp(your_mcp_server, mission=MISSION) ]

Tool calls are inspected in flight; a denied call returns an MCP error the client surfaces to the model, which is what lets it replan rather than fail blindly.

CLI

Exit codes make it a drop-in gate for pipelines and CI. The d4a package is a client for this API and nothing more — no scoring, no thresholds, no drift mathematics run on your machine.

pip install d4a          # no dependencies; the client is an HTTP client

d4a signup    --email you@company.com
d4a provision --mission "Resolve billing disputes within refund policy." \
              --tools lookup_invoice,issue_refund,escalate_to_human \
              --authority acme-deploy-key --cap issue_refund.amount:200
d4a check     --agent agt_… --tool issue_refund --args '{"amount":500}'
d4a usage
d4a audit     --agent agt_…

Verify it end to end, on your machine

Sixty seconds, no model key, no sign-up anywhere and no network: you start the service on your laptop and talk to it. What follows is a real transcript — the same commands, the same output.

1 · Start the service

cd C:\Apps\D4A          # or wherever you keep it
python3 cli.py serve --port 8123

With no database configured it uses SQLite in a file. For production you pass D4A_DB=postgres://… and the store changes, not the governance.

2 · Sign up and register an agent WITH its cap

curl -s localhost:8123/v1/signup -H 'Content-Type: application/json' \
  -d '{"email":"tu@empresa.com"}'
# -> {"api_key":"d4a_live_…","free_calls":1000, …}

curl -s localhost:8123/v1/agents -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{
    "mission": "Resolve billing disputes within refund policy.",
    "tools": ["lookup_invoice","issue_refund"],
    "signing_authority": "acme-deployment-key",
    "acknowledge_no_semantic_sensor": true,
    "hard_constraints": [{"tool":"issue_refund","arg":"amount","op":"<=","value":200}]
  }'
# -> {"agent_id":"agt_2e309d72c4084bf2","anchor_hash":"1500254eb6f0ec1b…"}

The cap has to be declared. If you leave it out, that cap does not exist and nothing checks it — that is not an oversight, it is the house rule: what you do not declare is not governed.

3 · Four steps, and what each one answers

POST /v1/agents/agt_…/step

  lookup_invoice                    -> ALLOW
  issue_refund {"amount":150}       -> ALLOW
  issue_refund {"amount":500}       -> BLOCK_ESCALATE
        admissibility:hard_constraint:issue_refund.amount=500 !<= 200
  drop_the_database              -> BLOCK_ESCALATE
        admissibility:tool_out_of_scope:drop_the_database

Both blocks come from admissibility, not from scoring: they are decided before any number is looked at, and no later score can re-admit them.

4 · The audit verifies itself

curl -s localhost:8123/v1/agents/agt_…/audit -H "Authorization: Bearer $KEY"
# -> "verify": {"ok": true, "first_broken": null, "detail": "verified 3 records"}
#    "head":   "27c524018969f4f5e018d2c4f9a53b7b…"

5 · The same over the CLI, with exit codes

d4a provision --mission "…" --tools lookup_invoice,issue_refund \
              --authority acme-key --cap issue_refund.amount:200

d4a check --agent agt_… --tool issue_refund --args '{"amount":150}'
# ALLOW            verdict=nominal cumulative=0.0000 admissible=True
# exit code = 0

d4a check --agent agt_… --tool issue_refund --args '{"amount":500}'
# BLOCK_ESCALATE   admissible=False  admissibility:hard_constraint…
# exit code = 2

Mind the --cap separator: it is a colon, issue_refund.amount:200. Written as amount<=200 the command is rejected with a message — the cap is never half-applied nor silently ignored.

Verdicts & gating

Graded, not binary — because a hard stop on every wobble is unusable, and a warning on a real breach is negligent.

Response fields

{
  "action":      "allow" | "warn_replan" | "block_escalate",
  "allow":       true,          // convenience booleans
  "block":       false,
  "verdict":     "nominal" | "warning" | "refuse",
  "cumulative":  0.1640,       // EWMA persistence, 0–1
  "max_streak":  15,           // longest per-channel streak
  "admissible":  true,          // false = hard structural violation
  "reason":      "…",          // human-readable; give this to the agent
  "protected":   true,          // false = observe-only, NOT enforcing
  "audit_seq":   41,
  "audit_head":  "9f2c…",       // hash-chain head after this step
  "usage":       { "calls_used": 41, "calls_remaining": 959 }
}

The mission anchor

The anchor is what everything is measured against. It is created at registration, signed by your deploy credential, hashed, and never mutated. There is no endpoint to edit it — changing the mission means registering a new agent, which is the point: a drifting agent must not be able to move its own goalposts.

Endpoints

Create an organisation and issue an API key. No auth. The key is shown once and stored only as a hash.

Register an agent; returns agent_id and anchor_hash.

List your registered agents.

Govern one step. This is the metered call.

Same, with agent_id in the body — convenient for thin clients.

The signed anchor as stored.

The hash-chained decision log plus a verification result.

Calls used, remaining, and amount due.

Liveness. No auth.

Step request fields

Errors & quota

// 402 — the free tier is a constructive refusal, not a wall
{
  "error": "free_tier_exhausted",
  "mode":  "REFUSE",
  "blocking_condition": "free tier of 1000 governed calls is exhausted",
  "reopening_conditions": [
    "start a contract to continue — diacroma@veritglobal.com",
    "we raise your quota the same day; your agents and anchors stay as they are"
  ]
}

Usage warnings appear in every response from 80% of the tier onward, so nobody discovers the limit mid-run.

If the governance layer is unreachable

Decide this deliberately. Fail-open (default) keeps your agent running ungoverned and alerts loudly — right for most products, because a governance layer that takes your agent down gets uninstalled on day one. Fail-closed refuses to act without a verdict — right for regulated or high-blast-radius work. Whichever you pick, say so in your own runbook.

What you declare, and what happens if you don't

The gate can only see what you told it to watch. No omission makes it fail open on what you did declare — what they do is reduce what it can see, and that is written into the signed profile that travels with every decision. This table is the complete list.

The rule, in one line: what you don't declare isn't governed, and we tell you at deploy time, not when something happens.

Three agents or more

Everything on this page governs one agent. For several to watch each other they do not need to talk: they need to declare what they read. It is optional — declare nothing and each agent is governed on its own, and coupling simply does not exist.

1 · Declare what each agent reads — at any of three moments

Optional, and all three are the same reads field. There are three because an agent discovers which data it needs while it works: if you could only declare at creation, everything it discovers later would stay invisible. The read set grows over the agent's life; it is not fixed at sealing.

// 1) when you create the agent
POST /v1/agents
{ "mission": "...", "tools": ["..."], "signing_authority": "...",
  "tenant": "acme",
  "reads": [{"collection": "invoices", "tier": 1, "key": "inv-1042"}] }
// -> { "agent_id": "agt_…", "reads_declared": 1, … }

// 2) at any time, as often as needed
POST /v1/agents/{agent_id}/reads
{
  "tenant": "acme",
  "reads": [
    {"collection": "invoices", "tier": 1, "key": "inv-1042"},
    {"collection": "customers", "tier": 2,
     "ranges": [["balance", 0, 5000]]},
    {"collection": "kb_policies", "tier": 3}
  ]
}
// -> { "declared": 3, "exact_keys": 1, … }

// 3) inside the step that uses the data
POST /v1/agents/{agent_id}/step
{ "proposed_tool": "…", "output_kind": "…", "tenant": "acme",
  "reads":  [{"collection": "kb_policies", "tier": 3}],
  "writes": [{"collection": "invoices", "key": "inv-1042"}] }

tenant is required in all three. Without a scope there is no partition, and an index that crosses tenants tells one customer that another is working: it is rejected at declaration time, not at evaluation.

Each tier marks a superset of the one before, so omitting the tier marks more, never less. Tier 3 is what stops a similarity query (RAG) from being a separate case: it cannot be expressed as a condition, but the collection can be declared. Declare nothing and nobody is ever marked.

2 · Declare what it writes, in the same governed step

There is no separate call: it rides on the /step you already make. Deliberately — a separate call would leave a window in which the step already happened and nobody is marked yet.

POST /v1/agents/{agent_id}/step
{
  "proposed_tool": "update_invoice",
  "tool_args": {"id": "inv-1042", "status": "voided"},
  "output_kind": "action",
  "tenant": "acme",
  "writes": [{"collection": "invoices", "key": "inv-1042"}]
}

Every agent that declared reading inv-1042 is now marked — and the mark carries how much exposure the writer had already spent. A clean writer dirties less than one that was already drifting.

3 · What the step returns: what you marked, and what you inherited

Two different things, so two fields. coupling is what this step moved under others. inherited is what others moved under this one — and that is the one that governs.

POST /v1/agents/{agent_id}/step
{
  "action": "block_escalate",
  "admissible": false,
  "reason": "admissibility:coupling_poisoned: 1 premise(s) moved …",
  "exposure": 1.87,

  // what THIS step marked (only if it declared `writes`)
  "coupling": { "marked": 3, "pivot": false },

  // what THIS step inherited (only if marks were pending)
  "inherited": {
    "marks": 2,
    "grade": "contaminated",
    "inherited_exposure_native": 700000000,
    "confidence_penalty": 0.50,
    "block": false,
    "degraded": false,
    "written_by": ["agt_charges", "agt_ledger"]
  }
}

What each one does to the decision — which is what separates this from a dashboard:

grade is stale (someone moved your premise), contaminated (and they were drifting) or poisoned (the writer was blocked, or claimed something with no receipt). pivot: true means this agent is the junction — it carries moved premises and what it writes is read by someone else. It is the one of the three to go and look at.

4 · Looking without charging

GET /v1/agents/{agent_id}/coupling
{
  "marks": 2, "grade": "contaminated", "pending": true,
  "inherited_exposure": 0.70, "inherited_exposure_native": 700000000,
  "confidence_penalty": 0.50, "block": false,
  "circulation": 0, "pending_lineage": 0,
  "written_by": ["agt_charges", "agt_ledger"]
}

This view does not consume. Read it a thousand times and the number does not move: it is what the next governed step will inherit — hence pending: true. The cycle consumes, and only if it commits: the mark deletion rides in the same transaction as the state and the audit row, so either all three land or none does. A GET that discounted what it measures would let a dashboard refreshing every thirty seconds eat the contamination before anyone paid for it.

5 · What exists in the library and is not an endpoint yet

Audit & replay

Every decision is one row in an append-only, SHA-256 hash-chained log. Tampering with any past row breaks every link after it, and verification reports the first broken sequence.

GET /v1/agents/{agent_id}/audit

{
  "verify": { "ok": true, "first_broken": null, "detail": "verified 41 records" },
  "head":   "9f2c…",
  "records": [ { "sequence": 0, "payload": {…}, "chain_hash": "…" } ]
}

Replay is deterministic: the same trajectory produces the same verdicts and the same hashes. That is what makes the log defensible to an auditor rather than merely informative.

Performance

There is no LLM on the governed path. A decision is arithmetic over six channels, a set lookup and one hash — so there is no model latency, no token cost, and no provider dependency.

Latency-critical agents (coding assistants) should use the in-process SDK and skip the network hop entirely. Measurements are reproducible: python3 tests/bench.py.

Security & privacy

What we store

By default the audit trail records digests and structured metadata — tool names, arguments checked against constraints, verdicts, hashes — not your agent's raw prompts or customer data. API keys are stored only as SHA-256 hashes; the plaintext key exists once, in the response to your signup call.

Isolation

Agents belong to an organisation. A key from one organisation cannot read or govern another's agents — that boundary is enforced on every request and covered by tests.

For regulated buyers

On-premises and in-VPC deployment are available so no agent traffic leaves your network at all, along with a DPA. Ask before you integrate rather than after.

Self-hosting Self-hosted

One dependency — the Postgres driver, and only if you point it at Postgres; with a SQLite file path it is standard library only. The container is small and starts in under a second. Mount a volume for the ledger, or give it a Postgres DSN, and point a hostname at it.

docker build -t d4agent .
docker run -p 8088:8088 -v d4a-data:/data d4agent

# or with no container at all
python3 -m service.app --port 8088

Self-hosting is licensed at a flat annual fee per site, not metered per call. Once the service runs in your infrastructure the usage ledger is your database, so the terms are contractual rather than technical: internal use, no redistribution, audit rights. Air-gapped installs welcome. Everything metered per governed step runs on the hosted API.

Next

See the live drift demo →
Pricing →
Get an API key →