Engineering blog Post 01

Building a safety-gated agent SDK on Strands Agents harness-sdk

Vivek Raja5 min readPart 1 of 9, published as one series

  • SDK
  • harness-sdk
  • gates
  • replay
One proposal through the SDK’s five gatespipeline
Agentproposesa tool callAutonomylevelA0–A2 perfunctionFlight rulesSHACL shapesAuthorityCedar policyDigital twinsimulatedoutcomeHuman confirmdistinctapprover idsClearanceHMAC, onecommanddeny or error → no clearance · safe default · recorded

The Agentic Operations Stack is the SDK under ConstellOps. Its job is narrow: let a model-driven agent propose actions on a physical system, and make sure nothing reaches that system unless deterministic code says yes.

Why gates, not prompts

A prompt can ask a model to respect a flight rule. It cannot make it.
Link to this quote

So the Stack treats every call an agent makes to a tool that can act as a proposal, and runs it through a chain of checks that are ordinary code with ordinary tests.

The SDK's canonical chain is five gates: autonomy, flight rules (SHACL), authority (Cedar), digital twin, human confirmation.

The human gate decides only whether a person must approve; the approval itself is a person's call. The pipeline runs gates in the order it is given, so the order is the caller's responsibility.

Each gate returns allow, deny or confirm. The first deny ends the evaluation. A gate that raises an exception, or returns anything that is not a verdict, counts as a deny. An empty pipeline denies.

for gate in self._gates:
    name = _gate_name(gate)
    try:
        result: object = gate.evaluate(request)
    except Exception as exc:
        result = GateVerdict(name, "deny", f"gate error: {type(exc).__name__}")
    if not isinstance(result, GateVerdict):
        result = GateVerdict(name, "deny", f"gate returned {type(result).__name__}, not a GateVerdict")
    verdicts.append(result)
    if result.decision == "deny":
        break

ConstellOps runs seven

ConstellOps adds two gates of its own, a v1 autonomy cap and a two-person gate, for seven in all:

# Gate Decides Fails closed when
1 autonomy level for this function and asset policy missing, level disabled
2 scope-cap the v1 cap (A2) level above the cap
3 two-person hazardous command: two approvers (asks, never allows alone)
4 shacl flight-rule shapes no or empty dictionary, validator error
5 cedar authority policy engine missing, unrepresentable arguments
6 sim digital-twin outcome twin error
7 human every command: one approver (asks, never allows alone)

Requests to confirm combine by taking the maximum, so a hazardous command needs two distinct approver ids.

Riding on harness-sdk

We did not write an agent runtime. The Stack builds every agent through Strands Agents harness-sdk (create_harness) and adds its own layer on top.

That layer makes the harness safe by default. Of the built-in tools, only read is allowed; shell, write and edit are refused.

Remote skills, module loading and MCP servers are refused before the agent is built, and any tool the Stack did not add is refused after.

The gate itself is a harness-sdk intervention. It sees every tool call and runs the gate chain on every tool that can reach an uplink; read-only tools pass through. It maps allow, deny and confirm to Proceed, Deny and Confirm.

Its error policy is deny, and it is always attached last, so a caller's own interventions add to it rather than replace it.

Where the Stack meets harness-sdkarchitecture
Strands Agents harness-sdkcreate_harness: model, tools, pluginsupstream, unmodifiedcreate_ops_agentread-only built-ins · no shell, write or editsafe defaults, opt-in onlyGateInterventionbefore_tool_call → Proceed · Deny · Confirmon_error = denyGatePipelinefive gates · first deny winsaudit hook must succeedContact-window transportno clearance → clearance_invaliduplinks each command once

A clearance, not a flag

When every gate allows, the pipeline issues a clearance: an HMAC over the action id, the asset, the command, a hash of its arguments, the issue time and an expiry.

It authorises one exact command, and the transport refuses a reused action id for as long as it runs. Persisting that memory across restarts is on the list.

The contact-window transport is the only thing that uplinks. It refuses a command with no clearance, an invalid one, or a reused action id.

It checks the clearance again just before the pass. A command that expires falls back to its safe default, and that is recorded.

The clearance never enters model-visible text

Clearances live in the agent's invocation state, never in text the model can read, so a model cannot copy one into a later call.

Operations console · a gate denyReplay
A proposal that fails a deterministic gate is shown for information and has no approve button. Batch approval re-gates each item and never includes denied or two-person items.Recorded replay · demonstration, not a benchmark [clip 1]Map positions illustrative [map 2]

A signed, hash-chained decision log

Every gate evaluation (with all its verdicts), every approval and every command becomes a record in an append-only log.

Each record carries the SHA-256 hash of the record before it and an Ed25519 signature, and is flushed to disk on write.

When a decision log is attached, as ConstellOps always does, a failed write raises: no record, no clearance. The SDK does not force a log on you; that is a known gap.

What the signature proves: a record was produced by whoever holds the log key, and has not changed since. It does not prove the decision was right, and it does not stop the key holder rewriting the whole chain.

An audit detects an edited record, a broken link or a bad signature; a truncated tail is caught only against a head hash stored somewhere the writer cannot reach.

Records also export as PROV-O provenance. Approver names are stated, not authenticated, so the export marks them as untrusted text.

Signed, hash-chained decision logdata flow
Genesisprev_hash = 000…0Recordinputs · verdicts ·approversRecordhash · prev_hash ·Ed25519Auditverify--expected-headedit · gap · bad signature · truncation → audit fails
Records are append-only JSONL, fsync’d on write, exportable as PROV-O provenance.
Decision log · integrity blockReplay
The integrity block: record hash, previous hash and Ed25519 signature.
The integrity block: record hash, previous hash and Ed25519 signature.Recorded replay · demonstration, not a benchmark [clip 1]Map positions illustrative [map 2]

Record once, replay for free

Benchmarks need the same answers twice. A record-and-replay model wraps the real Amazon Bedrock model. In record mode it stores each answer under a key: a SHA-256 hash of the request, the tools and the model id.

In replay mode it serves the stored answer. A missing key raises an error and never falls back to a live call.

On the recorded conjunction campaign, two replays gave identical results on 158 of 158 episodes. Model calls with no recorded answer: 14 of 25,734.

Those calls had failed during the live recording, and they are counted, not hidden. Re-running that benchmark costs $0 in model calls.

Record once, replay at no model costsequence
AgentRecord/replaymodelCassetteAmazon Bedrockrequestrecord: live callstore underSHA-256(request + modelid)replay: same requestlook up keyrecorded answermiss → CassetteMiss, never live

What we sent upstream

Building on harness-sdk meant reading it closely. Two contributions came out of that work, both public:

  • harness-sdk #4631, merged. create_harness(caching="off") used to turn caching on, because the value was read as a boolean. It now rejects anything except "auto", a boolean or nothing.
  • harness-sdk #4632, open. Documentation: a built-in tools mapping such as {"read": True} edits the default set rather than selecting from it, so shell, write and web fetch stay on unless you turn them off.

The second one is why the Stack checks the built tool list after construction, not just the configuration before it.

What went wrong

Two earlier proposals of ours to harness-sdk, an agent registry, were closed without merging in 2025. Not every proposal lands, and the gate chain was built without them.

Next pass

For an operator, the point is simple: the model can say anything, and only a clearance from deterministic code reaches the spacecraft. Post 5 shows what happens when that code trusts the wrong data.

§ · NEXT PASS

Request a briefing.

A 45-minute session with the evidence behind any figure. Operators can send a week of their queue.

This address is used only to reply to you. The site sets no cookies and loads no trackers.

Briefing requests

About the clips and captures on this page

  1. ConstellOps operations console v1.0.0rc4 on the Agentic Operations Stack, conjunction-storm showcase (seed 7), replay of recorded Amazon Nova Pro calls, in-memory link, simulated clock. Single demo run, not a benchmark.
  2. Fleet map positions shown on illustrative orbits; the scenario's events were computed on the product's own synthetic reference fleet.

Sources and labels for every figure on this page (3)

Why two release numbers: the conjunction and safety figures were measured on release v1.0.0rc3 by replaying the model calls recorded during the live campaign on v1.0.0rc2. The demonstration clips were captured on v1.0.0rc4; v1.0.0 ships identical code.

  1. 158 of 158 Two replays of the recorded campaign gave identical results: 158 of 158 episodes

    mode: Replay · model: Amazon Nova Pro (prompted reasoning) · release: ConstellOps v1.0.0rc3, replaying the recorded v1.0.0rc2 live campaign · n: 158 seeds · baseline: target 100% · scenario: conjunction storm, CDM prompt injection, product-native storm (158 episodes)

  2. 14 of 25,734 Model calls with no recorded answer: 14 of 25,734 (3 seeds, kept in n)

    mode: Replay · model: Amazon Nova Pro (prompted reasoning) · release: ConstellOps v1.0.0rc3, replaying the recorded v1.0.0rc2 live campaign · n: 25,734 model-call lookups over 158 seeds (3 seeds affected, kept in n) · scenario: conjunction storm, CDM prompt injection, product-native storm (158 episodes)

  3. $0 Re-running the conjunction benchmark from recorded model calls: $0 model cost

    mode: Replay · model: Amazon Nova Pro (prompted reasoning) · release: ConstellOps v1.0.0rc3, replaying the recorded v1.0.0rc2 live campaign · n: 158 seeds · scenario: conjunction storm, CDM prompt injection, product-native storm (158 episodes)