DEV Community: João André Gomes Marques

Asqav TypeScript SDK is live

João André Gomes Marques — Mon, 27 Apr 2026 18:51:51 +0000

If your AI agents run on TypeScript, you have probably noticed every governance and observability tool in the space treats Python as the default and JavaScript as an afterthought. We did the same thing for a while. Today we ship the fix.

npm install @asqav/sdk

Same REST API as the Python SDK, same ML-DSA-65 signatures generated server-side, same audit trail. The npm package is a thin client that hits api.asqav.com - all crypto stays on our infrastructure. Public surface mirrors Python one-for-one so you can write the same code in either language and get the same behaviour.

Thirty-second example

import { init, Agent } from "@asqav/sdk";

init({ apiKey: process.env.ASQAV_API_KEY });

const agent = await Agent.create({ name: "support-bot" });
await agent.startSession();

const sig = await agent.sign({
  actionType: "stripe.refund",
  context: { amount: 1500, reason: "customer dispute" }
});

console.log(sig.verificationUrl);
// https://asqav.com/verify/sig_abc123
await agent.endSession({ status: "completed" });

That signature is real ML-DSA-65 (FIPS 204), anchored to Bitcoin via OpenTimestamps, retrievable from any compliance auditor without needing your infrastructure online. Same guarantees as the Python flow.

What this unlocks

The interesting frameworks for agents in TypeScript right now are Vercel AI SDK, LangChain.js, and Mastra. Each one gives you a tool-calling loop where the model picks an action, you execute it, and the result feeds back. None of them give you a tamper-evident record of what the agent actually did.

With the npm SDK, wrapping a Vercel AI SDK tool to sign every call is six lines:

import { tool } from "ai";
import { Agent } from "@asqav/sdk";

const agent = await Agent.create({ name: "support-bot" });

const refund = tool({
  description: "Issue a refund",
  parameters: z.object({ amount: z.number(), customer: z.string() }),
  execute: async (args) => {
    await agent.sign({ actionType: "stripe.refund", context: args });
    return await stripe.refunds.create(args);
  }
});

Every refund the model decides to issue now has a signature on the way out. Replace the wrapper at the framework level and every tool gets governance for free.

Why we waited

Honest answer: shipping a second SDK doubles the surface to maintain. We held off until the Python SDK API stabilised so the TypeScript port could mirror it cleanly instead of forking immediately. The two are now version-locked at the API level - what works in one works in the other. Releases are independent (py-v0.2.22, ts-v0.1.0) so we can patch one without touching the other.

Install matrix

Both languages, same brand, same backend:

# Python
pip install asqav

# TypeScript / Node / Deno / Bun
npm install @asqav/sdk

Source: github.com/jagmarques/asqav-sdk (monorepo with python/ and typescript/ side by side, MIT). Docs and dashboard: asqav.com/docs. Get an API key at asqav.com and sign your first action in under a minute.

If you are wiring this into Vercel AI SDK or LangChain.js right now and hit a rough edge, open an issue on the SDK repo and we will turn it around fast. The TypeScript surface is fresh and we want to harden it against real usage before more frameworks land on top.

Try asqav in 30 seconds

João André Gomes Marques — Mon, 20 Apr 2026 12:38:26 +0000

Most agent governance tools want you through a signup flow before you see a single screen. We shipped asqav demo so you can see the product without an account.

pip install asqav[cli]
asqav demo

That opens a local dashboard at http://localhost:3030 with four pre-loaded scenarios. No API key, no Docker, no cloud call. The HTTP server runs entirely inside the SDK.

What you see

Four risky agent actions, each with the full context a reviewer would need to decide:

Claude Code wants to rm -rf ~/projects. High risk, destructive filesystem rule fires.
Fintech agent wants to send an 850 000 EUR wire. Amount over threshold triggers HITL.
DevOps agent wants to scale production to zero. Namespace + replicas rule blocks it.
Clinical agent wants to order CT with contrast, allergy not checked. Medium risk, reviewer sees the gap.

Each card renders six fields: action payload, agent reasoning chain, risk classification with reason, triggering policy name and rule, a required reason textarea (minimum ten characters), and an expected diff preview. Approve or Deny produces an HMAC-signed receipt. The dashboard re-verifies each receipt in the browser and shows whether the signature is valid.

Why we built it

Agent governance sits at the top of a long conversation before engineers start wiring SDKs into their code. A demo that runs without a network, without an account, and without a container gives the technical buyer a working artifact to share in thirty seconds. The rest of the integration - real policies, cloud signatures, dashboard - follows once the team agrees this is the shape they want.

What this is not

The receipts in the demo use HMAC over canonical JSON. Production asqav uses ML-DSA-65 (FIPS 204) signatures and RFC 8785 JCS canonicalization. Swap asqav demo for asqav.init(api_key="sk_...") and you get the real cryptography, the multi-party signing, the incidents and compliance reports. The demo is a preview of the UX and the audit flow, not a stand-in for the production trust chain.

Source and docs

asqav demo lives in the SDK, Apache 2.0: github.com/jagmarques/asqav-sdk
Approval card UX in the real dashboard: docs/approvals
Attestation format (third-party verifiable, RFC 8785): docs/attestation

Governance metadata in A2A Agent Cards, shipping the superset

João André Gomes Marques — Sun, 19 Apr 2026 19:56:38 +0000

A2A Agent Cards describe what an agent can do, where it lives, and how to talk to it. What they do not describe is governance posture. Two agents can hold identical cards and behave nothing alike in production.

We shipped a reference implementation under extensions.asqav.governance inside the standard AgentCard envelope. Three fields carry the posture: trust_score, retention_ttl_seconds, and derivation_rights. Signed with the agent's own ML-DSA-65 keypair. Docs at asqav.com/docs/a2a.

The schema

{
  "name": "research-agent",
  "url": "https://agents.example.com/research",
  "extensions": {
    "asqav.governance": {
      "version": 2,
      "agent_id": "agt_x7y8z9",
      "trust_score": 0.82,
      "retention_ttl_seconds": 2592000,
      "derivation_rights": {
        "retention_permitted": true,
        "derivative_works": false,
        "third_party_sharing": false,
        "license_reference": "https://example.com/licenses/research-v1"
      },
      "issued_at": "2026-04-19T12:00:00+00:00",
      "expires_at": "2026-04-26T12:00:00+00:00",
      "signature": "...",
      "public_key": "..."
    }
  }
}

Why trust_score decays

A discrete L0 to L3 grade hides real signal. An agent that ran clean 90 days ago then went silent is epistemically different from one that just handled a thousand signed actions. A decaying score separates them. 45-day half-life on positive evidence: each successful signed action contributes weight 0.5 ^ ((now - t) / 45 days). Negative events (suspensions, revocations) apply full-weight penalties that do not decay. Derivation reads signed records only, so independent verifiers get the same number.

Why derivation_rights needs license_reference

derivative_works: false alone means nothing across organizations. One side reads it as "do not train on my outputs," another as "do not fine tune downstream," another as "do not incorporate into product." The boolean is a coarse intent signal. license_reference pins down the actual contract, whether that is a CC license, a bespoke DUA, or a proprietary TOS. Machine-readable gating and human-readable legal terms in the same envelope.

Key rotation

Each agent signs its own extension with its own ML-DSA-65 keypair. The public key is embedded in the signed envelope at issuance time, not fetched by reference. When a key rotates, old attestations stay verifiable forever because the bytes needed to check the signature are already inside the envelope. A third party that captured an attestation in February does not have to call back to asqav in October to confirm it.

curl https://api.asqav.com/api/v1/public/attestation/agt_x7y8z9

Platform discovery is standard A2A: GET /.well-known/agent.json. Per-agent cards at GET /api/v1/agents/{id}/card. Parse like any A2A card, look inside extensions if you care about posture.

Portable Trust for AI Agents

João André Gomes Marques — Sun, 19 Apr 2026 15:43:38 +0000

When two autonomous agents from different organizations talk to each other, they have to decide whether to trust each other's actions. Today that decision is mostly opaque. One side has its own scoring, the other side has its own thresholds, and reconciliation across providers comes down to whose guardrails you ran through last.

A recent A2A protocol discussion surfaced the underlying gap. If every layer introduces its own score, grade, or tier, two independent systems cannot deterministically arrive at the same decision, even when every individual signal was valid and signed. What is missing is a notion of decision identity, something that lets different representations be verified as equivalent outcomes rather than as locally consistent ones.

Governance Attestation is our answer. It is a single signed JSON per agent that any party can fetch, verify offline with ML-DSA-65, and act on without calling our API. One canonical document, one deterministic trust level, one mapping published in our docs.

What is in an attestation

{
  "version": 1,
  "agent_id": "agt_x7y8z9",
  "issuer": "asqav",
  "trust_level": "L2",
  "capability_manifest_hash": "sha256:3f2a...",
  "policy_digest": "sha256:91c4...",
  "compliance_attestations": ["eu_ai_act_art12", "soc2_audit"],
  "issued_at": "2026-04-19T12:00:00+00:00",
  "expires_at": "2026-04-26T12:00:00+00:00"
}

The body is canonical JSON, signed with the agent's post-quantum ML-DSA-65 key. Signature, public key, and verify URL come back alongside the body. Two independent verifiers recomputing the canonical bytes of the body get the same digest, run the same signature check, and reach the same decision. That is what deterministic trust looks like at the protocol layer.

The trust levels

Four canonical levels, derived deterministically from the agent's state. No subjective scoring.

L0 Unknown - default. No signed activity in the last 30 days.
L1 Monitored - at least one signed action in the last 30 days.
L2 Governed - L1, and the owning organization has at least one enabled policy.
L3 Autonomous - L2, and no revocation or suspension in the last 90 days.

Because the rules are public, an auditor can reconstruct the level from the raw signed records. If they disagree with the outcome, the argument is about the rules, not about whose internal scoring they trust.

The public verify path

curl https://api.asqav.com/api/v1/public/attestation/agt_x7y8z9

No auth. No API key. Any third party fetches the signed envelope. The signature verifies offline against the returned public key using ML-DSA-65. The canonical body tells them the trust level, capability hash, policy digest, and the exact window the attestation is valid for.

A2A Agent Card integration

For agents exchanging Agent Cards through A2A, drop the attestation URL and hash into your card. Recipients verify the governance posture before accepting a request.

{
  "name": "research-agent",
  "governance": {
    "provider": "asqav",
    "attestation_url": "https://asqav.com/attestation/agt_x7y8z9",
    "attestation_hash": "sha256:..."
  }
}

Issuing an attestation

POST /api/v1/agents/{agent_id}/attestation
X-API-Key: sk_live_...

A fresh attestation expires after seven days, at which point you issue a new one. That window is short on purpose. Trust is a function of recent behavior, not a static label attached once.

Why this exists on Enterprise

Governance Attestation is a cross-organization trust primitive. It only pays off when you are operating agents that talk to other organizations' agents, usually under contract, usually with legal and compliance sitting on the other side of the table. That is the shape of Enterprise deployments.

For single-organization setups, audit trails, policy enforcement, and the public verify endpoint still cover everything.

Full docs: asqav.com/docs/attestation

Sign the intent, the decision, and the execution

João André Gomes Marques — Wed, 15 Apr 2026 17:36:20 +0000

Most governance tools produce a single signed receipt after the fact. The action happened, here is the proof. That approach covers you in the simplest case, but it leaves two critical moments completely unrecorded.

The first is intent. Before an agent runs anything, it declares what it wants to do. That declaration is worth signing on its own, because it tells you what the agent was trying to accomplish regardless of whether it was allowed to proceed. The second is the policy decision itself, the moment your rules evaluated the request and returned an approval or a denial. If you only sign the final action, you lose both of these, and you are left with no proof that governance actually ran before the agent acted.

Three-phase signing treats each of these moments as a separate signed record in a chain. The intent gets signed first, capturing the agent, the action, and the context it provided. The decision gets signed next, recording whether the policy approved or denied the request and which rules were evaluated. If the request was approved, the execution gets signed last, confirming the action completed.

The interesting case is when the policy blocks the action. You still end up with two signed records: the intent and the denial. That means you have a tamper-proof record showing that the agent tried to do something it was not allowed to do, and that your governance layer caught it. For compliance, this is just as valuable as a successful execution chain, because auditors want to see that controls are working, not just that actions happened.

import asqav

asqav.init(api_key="sk_...")
agent = asqav.Agent.create("orchestrator")

chain = agent.sign_with_phases("data:delete:users", {"table": "users", "reason": "cleanup"})

print(chain.intent)      # signed: agent wanted to delete users
print(chain.decision)    # policy evaluated and approved/denied
print(chain.execution)   # signed: action completed (only if approved)
print(chain.approved)    # True/False

Each phase in the chain is individually verifiable. You can hand an auditor the intent signature alone and they can confirm it is authentic without needing the rest of the chain. Or you can export the full chain as a single bundle and let them walk through the entire lifecycle of the action from request to completion.

This also changes how you think about denied actions. Instead of treating a policy denial as a silent non-event, it becomes a first-class record in your audit trail. Over time, the pattern of denied intents tells you as much about your agents as the approved ones do, because it shows you what they are consistently trying to do and being stopped from doing.

CrewAI GuardrailProvider

On a related note, we recently shipped a GuardrailProvider integration for CrewAI that plugs three-phase signing directly into crew task execution. If you are building with CrewAI, the guardrail provider evaluates each agent action against your policies and produces the same signed chain automatically, so you get full intent, decision, and execution records without changing how your crews are structured.

Source on GitHub. If something breaks, open an issue.

Trace agent actions across workflows and kill everything in one call

João André Gomes Marques — Wed, 15 Apr 2026 17:05:58 +0000

Two problems kept coming up while I was building multi-step agent workflows.

First, when an orchestrator delegates to sub-agents, the audit trail turns into a mess. You get a flat list of signed actions with no way to tell which ones belong to the same workflow. Was that data:read from the reporting pipeline or the cleanup job? No idea.

Second, when something goes sideways in production, you need to stop every agent in your organization immediately instead of figuring out which one is causing the problem.

Trace correlation

trace_id solves the first problem. Generate one ID for the workflow, then pass it to every sign() call. Every action in that workflow shares the same trace, so you can reconstruct exactly what happened and in what order.

import asqav

asqav.init(api_key="sk_...")
agent = asqav.Agent.create("orchestrator")

# Generate a trace ID for the whole workflow
trace_id = asqav.generate_trace_id()

# Every action in this workflow shares the same trace
agent.sign("task:start", {"step": "fetch"}, trace_id=trace_id)
agent.sign("task:delegate", {"to": "sub-agent"}, trace_id=trace_id, parent_id="sig_abc")
agent.sign("task:complete", {"result": "done"}, trace_id=trace_id)

The parent_id parameter links delegated actions back to the signature that spawned them. So you get a tree, not a list. The orchestrator signed task:delegate, and the sub-agent's actions reference that signature as their parent.

This matters for compliance. When an auditor asks "show me everything this workflow did," you filter by trace_id and get a complete, ordered chain of signed actions. No guessing, no log correlation hacks.

Emergency halt

The second problem is simpler but scarier. An agent starts behaving unpredictably, or you detect a security incident, and you need a kill switch.

# Something goes wrong? Kill everything.
asqav.emergency_halt(reason="security incident")

One call. Every agent registered under your organization gets revoked immediately. Their signatures stop verifying, their scope tokens become invalid, and any in-flight actions get rejected. The halt reason gets recorded in the audit trail so you have a clear record of when and why you pulled the plug.

You can also halt a specific agent or agent group instead of the whole org. But the point of emergency_halt() with no target is that you do not need to figure out which agent is the problem when things are on fire. Stop everything, investigate after.

Why this matters

Agent workflows are getting more complex. An orchestrator calls a planner, the planner calls three workers, each worker calls external APIs. Without trace correlation, you are debugging in the dark. Without an emergency halt, you are hoping nothing goes wrong.

Both features ship in the latest version:

pip install asqav --upgrade

Full docs at asqav.com/docs. Source on GitHub. If something breaks, open an issue.

Stop replay attacks on AI agent tokens

João André Gomes Marques — Wed, 15 Apr 2026 06:31:20 +0000

Scope tokens let you prove what an AI agent is allowed to do. I wrote about portable scope tokens a few days ago. They travel with requests so the receiving service can verify permissions without calling back to your org.

But there is a problem I did not cover. If someone intercepts a valid scope token, they can replay it. The token is signed, unexpired, and carries legitimate permissions. Nothing stops a second use.

The replay problem

Say your agent creates a scope token with data:read permission and a one-hour TTL. It sends a request to a partner API with the token attached. An attacker sitting on the network copies that token. They now have 59 minutes to make their own requests using the same token, with the same permissions.

The signature still verifies. The TTL has not expired. The actions list matches. From the receiver's perspective, the replayed request looks identical to the original.

Short TTLs reduce the window but do not close it. Even a 60-second TTL gives an attacker 60 seconds.

Nonce-based replay protection

The fix in v0.2.14 is straightforward. Every scope token now includes a unique nonce, a random string generated at creation time. The receiver tracks which nonces it has already seen. If a nonce shows up twice, the token gets rejected.

import asqav

agent = asqav.Agent.create("api-caller")
token = agent.create_scope_token(actions=["data:read"], ttl=3600)

# Each token has a unique nonce
print(token.nonce)  # "a1b2c3d4..."

# Receiver side
seen_nonces = set()
if asqav.is_replay(token.nonce, seen_nonces):
    raise ValueError("Replay detected")
seen_nonces.add(token.nonce)

The pattern is simple: generate, check, reject duplicates. The nonce set only needs to hold entries until the token's TTL expires. After that, the token is invalid anyway, so you can clean up old nonces.

Why not just use shorter TTLs

Shorter TTLs help. But they create a different problem. Your agent needs to mint new tokens more frequently, adding latency to every request. And even a 1-second TTL is vulnerable to automated replay within that window.

Nonces and TTLs work together. The TTL limits how long the nonce set needs to persist. The nonce ensures each token is truly single-use regardless of TTL length.

Implementation notes

For most setups, an in-memory set works fine. If you are running multiple receiver instances behind a load balancer, you need a shared store like Redis so all instances see the same nonce set.

The is_replay helper handles the check and cleanup for you. Pass in the nonce and your set. It returns True if the nonce was already seen.

# Production setup with Redis
import redis
r = redis.Redis()

def check_nonce(token):
    key = f"nonce:{token.nonce}"
    if r.exists(key):
        raise ValueError("Replay detected")
    r.setex(key, token.ttl, 1)

Install or upgrade:

pip install asqav --upgrade

Docs at asqav.com/docs. Source on GitHub. If something breaks, open an issue.

Portable scope tokens: prove what your agent can do without calling home

João André Gomes Marques — Tue, 14 Apr 2026 12:40:52 +0000

Your agent authenticates with an API key. The external service knows who is calling. But it has no idea what the agent is actually allowed to do.

This is the gap between authentication and authorization in agent-to-service communication. Auth tokens prove identity. They do not prove permission. When agent A calls external service B, B can verify that A is a legitimate caller, but it cannot verify that A has been authorized to read customer data, trigger a payment, or access a specific endpoint.

The problem with calling home

The traditional fix is for service B to call back to A's organization and ask "is this agent allowed to do this?" That works when both services are inside the same network. It falls apart when agents interact with third-party APIs, partner services, or any system outside the org boundary. The callback adds latency, creates a runtime dependency, and requires the external service to know how to reach your authorization system in the first place.

Most teams skip this entirely. They give agents broad API keys and hope the agent only does what it should. That is not a security model. That is wishful thinking.

Scope tokens

A scope token is a signed, portable proof of what an agent is authorized to do. You create it before the agent makes an outgoing request. It lists the specific actions the agent is permitted to perform, has a time-to-live, and is signed by Asqav as an independent third party.

The token travels with the request. The receiving service verifies the signature using Asqav's public key, checks the action list and expiry, and makes its access decision. No callback to your org. No shared secret. No runtime dependency.

import asqav

asqav.init(api_key="sk_...")
agent = asqav.Agent.create("api-caller")

# Create scope token before calling external API
token = agent.create_scope_token(
    actions=["data:read:customer", "api:call:external"],
    ttl=3600
)

# Attach to outgoing request
import requests
requests.get("https://partner-api.com/data", headers=token.to_header())

The token gets attached as an X-Agent-Scope header. On the partner side, verification is one call.

# Partner side - verify without calling your org
received = asqav.verify_scope_token(request.headers["X-Agent-Scope"])
if received and "data:read:customer" in received.actions:
    # Verified: agent is authorized for this scope
    pass

What makes this different from OAuth scopes

OAuth scopes are declared during the authorization flow and embedded in the access token. The resource server trusts the authorization server that issued the token. Scope tokens work differently. They are issued per-request (or per-session), signed by an independent third party, and verifiable by anyone with the public key. The receiving service does not need a pre-existing trust relationship with your authorization server.

This matters for agent-to-agent communication. When your agent calls a partner's agent, there is no shared OAuth provider. Scope tokens give both sides a common verification mechanism without requiring either to adopt the other's auth infrastructure.

Practical constraints

Scope tokens are intentionally short-lived. The ttl parameter sets the expiry in seconds. A token created with ttl=3600 is valid for one hour. After that, the receiving service rejects it. This limits the blast radius if a token leaks.

Actions follow a hierarchical format: resource:operation:target. The format is flexible enough to model most permission structures but specific enough to verify programmatically.

Getting started

pip install asqav

Full docs at asqav.com/docs. Source on GitHub. If something does not work the way you expect, open an issue.

Replay what your AI agent did, step by step

João André Gomes Marques — Tue, 14 Apr 2026 09:12:47 +0000

If you're running AI agents in production, you probably have some form of audit trail already. Maybe signed receipts, maybe logs, maybe just hope. But here's the thing, when something goes wrong or an auditor shows up, nobody wants to read raw JSON.

They want to walk through what the agent did. Step by step. In order.

The problem with raw receipts

I've been building asqav for a while now, and the signed action receipts work great as cryptographic proof. Each action gets signed, each signature is chained to the previous one, and you get tamper-evident records of everything your agent did.

But proof and readability are different things. When you're debugging an incident at 2am or preparing for a compliance review, you need a timeline you can actually follow. Not a folder of JSON blobs.

asqav.replay()

The new replay feature takes your signed receipts and turns them into a walkable timeline. It fetches all actions for a given session, orders them chronologically, verifies the hash chain is intact, and hands you something you can actually read.

import asqav

asqav.init(api_key="sk_...")
timeline = asqav.replay(agent_id="agt_abc123", session_id="sess_xyz")

# Human-readable summary of what the agent did
print(timeline.summary())

# Each step in order
for step in timeline.steps:
    print(f"{step.timestamp} - {step.action} - {step.status}")

# Verify nothing was tampered with
assert timeline.chain_integrity  # True if hash chain is valid

The chain integrity check is the key part. It doesn't just replay events. It re-verifies every link in the hash chain. If someone deleted a step, modified an action, or inserted something after the fact, it catches it.

Offline compliance bundles

Not every auditor wants to hit your API. Some want a self-contained package they can review independently. That's what export bundles are for.

# Export a compliance bundle with all signatures
bundle = asqav.export_bundle(signatures, "eu_ai_act_art12")

# Anyone can replay from the bundle - no API access needed
timeline = asqav.replay_from_bundle(bundle)
print(timeline.summary())

The bundle includes all the signed actions, the public keys needed to verify them, and metadata about which compliance framework it targets.

Why this matters now

The EU AI Act Article 12 requires that high-risk AI systems maintain logs that enable "the reconstruction of the system's activity." Signed receipts are the proof that your agent did what it says it did. Replay is how you present that proof to someone who needs to understand it.

This isn't theoretical compliance. If you're deploying agents in the EU (or selling to companies that operate there), you'll need reconstructable audit trails. The regulation is already in force for some categories.

Try it

asqav is open source and the SDK is on PyPI:

pip install asqav

The replay feature ships in the next release. If you want to get started with signed audit trails today, the quickstart takes about five minutes.

Repo: github.com/asqav/asqav

One-click compliance bundles for AI agent audits

João André Gomes Marques — Mon, 13 Apr 2026 15:28:51 +0000

An auditor walks in and asks for evidence that your AI agents are governed. You have signing data scattered across API responses, CSVs from different time ranges, and a vague explanation of how your Merkle verification works. Good luck putting that together under time pressure.

This is the compliance evidence problem. You have the data, but packaging it into something an auditor can actually verify takes hours of manual work.

Compliance bundles in asqav 0.2.11

The new export_bundle function takes a list of signatures and a compliance framework identifier, then returns a self-contained JSON document with a Merkle root. One file. Everything an auditor needs.

import asqav

asqav.init(api_key="sk_...")
agent = asqav.Agent.create("compliance-demo")

# Collect signatures from your agent pipeline
signatures = []
signatures.append(agent.sign("sql-read", {"query": "SELECT * FROM users"}))
signatures.append(agent.sign("http-external", {"endpoint": "api.openai.com"}))
signatures.append(agent.sign("file-write", {"path": "/reports/q1.pdf"}))

# Package into a compliance bundle
bundle = asqav.export_bundle(signatures, "eu_ai_act_art12")
bundle.to_file("audit-q1-2026.json")

The output JSON contains the framework metadata, every signature receipt, individual receipt hashes, and a Merkle root computed over all of them. An auditor can independently verify the root by re-hashing the receipts.

Four supported frameworks

The framework parameter accepts four values out of the box:

eu_ai_act_art12 - EU AI Act Article 12 record-keeping requirements
eu_ai_act_art14 - EU AI Act Article 14 human oversight requirements
dora_ict - Digital Operational Resilience Act (DORA) for financial services
soc2 - SOC 2 Type II audit evidence

Each framework maps to specific metadata that gets embedded in the bundle, so the auditor knows exactly which standard the evidence targets.

What is in the bundle

The ComplianceBundle dataclass gives you several ways to work with the data:

# Inspect before saving
print(bundle.merkle_root)     # SHA-256 Merkle root
print(bundle.receipt_count)   # Number of signatures included
print(bundle.framework)       # "eu_ai_act_art12"

# Export options
bundle.to_file("audit.json")  # Write to disk
json_str = bundle.to_json()   # Get JSON string
data = bundle.to_dict()       # Get plain dict

The verification section of the JSON includes the Merkle root, the hash algorithm (SHA-256), and individual receipt hashes so anyone can rebuild the tree and confirm nothing was tampered with.

How it fits into a real workflow

You probably already have signatures from your agent pipeline. The typical flow looks like this:

Your agents run and sign actions through asqav (LangChain, CrewAI, whatever framework you use)
At the end of an audit period, pull signatures via asqav.export_audit_json()
Feed them into asqav.export_bundle(signatures, "eu_ai_act_art12")
Hand the auditor one JSON file

No more exporting CSVs. No more explaining your signing pipeline. The bundle is self-describing and independently verifiable.

Getting started

pip install asqav==0.2.11

The compliance module works entirely client-side. Merkle root computation happens locally using SHA-256, so no extra API calls are needed beyond the signatures you already have.

GitHub | Docs

Test AI agent governance without touching production

João André Gomes Marques — Mon, 13 Apr 2026 15:24:18 +0000

You built an AI agent pipeline. It works. Users depend on it. Now someone asks you to add governance: audit trails, policy checks, cryptographic signing. Reasonable request. But the thought of plugging a new library into a production pipeline makes your stomach turn.

What if it adds latency? What if a signing failure kills a chain run? What if a policy misconfiguration blocks legitimate actions?

This is the observe mode problem. You need to see what governance would do before you let it do anything.

The solution: observe mode

asqav 0.2.11 ships an observe flag on every framework adapter. When enabled, the handler logs every action it would sign but makes zero API calls. Your pipeline runs exactly as before. You just get visibility into what governance would look like.

import asqav
from asqav.extras.langchain import AsqavCallbackHandler

asqav.init(api_key="sk_...")

# observe=True: logs actions, never calls the signing API
handler = AsqavCallbackHandler(
    agent_name="my-agent",
    observe=True,
)

chain.invoke(input, config={"callbacks": [handler]})
# Check your logs for lines like:
# OBSERVE: would sign chain:start with context {...}
# OBSERVE: would sign llm:start with context {...}

The handler hooks into every chain start, tool call, and LLM interaction. With observe=True, each event gets logged with the exact action type and context that would have been signed. No network calls. No latency. No risk.

Once you are comfortable with what you see in the logs, flip observe=False and governance goes live.

Semantic patterns instead of glob strings

Another friction point: action type strings. In older versions you had to remember namespaces like data:delete:* or api:call:external:*. Now you can use semantic labels:

agent = asqav.Agent.create("db-agent")

# Before: agent.sign("data:delete:*", {"table": "users"})
# Now:
agent.sign("sql-destructive", {"table": "users"})

The SDK resolves sql-destructive to data:delete:* internally. Other built-in patterns include sql-read, file-write, http-external, shell-execute, pii-access, and more. You can still use raw glob strings if you prefer.

Preflight with plain-English explanations

Before 0.2.11, agent.preflight() returned a boolean and a list of reason codes. Now it includes a human-readable explanation:

result = agent.preflight("sql-destructive")

print(result.cleared)      # False
print(result.explanation)   # "Blocked: action not permitted by current policy rules"
print(result.reasons)       # ["blocked by policy: no-delete-production"]

This is useful for debugging policy configurations and for showing end users why an agent action was denied.

Getting started

pip install asqav==0.2.11

The SDK is open source, MIT licensed, and works with LangChain, CrewAI, LlamaIndex, OpenAI Agents, smolagents, DSPy, LiteLLM, and Haystack. Start with observe mode, review the logs, then go live when you are ready.

GitHub | Docs

Layer 1 is identity, Layer 2 is attestation

João André Gomes Marques — Sun, 12 Apr 2026 17:01:12 +0000

AI agents are getting identity systems. DIDs, Ed25519 signatures, certificate-based auth. The tooling is growing fast. Microsoft shipped Entra agent identity. AgentNexus brought decentralized identifiers to autonomous agents. This is good work.

But identity only answers one question: who is this agent?

It does not answer the harder question: what did this agent actually do, and can it prove it?

Two layers, two problems

You can think of agent governance as a stack with two layers.

Layer 1 is identity. The agent holds a signing key. It can prove who it is to other systems. DID documents, Ed25519 keypairs, X.509 certificates. These all live here. The agent controls the key and uses it to authenticate.

Layer 2 is attestation. A separate system, one the agent does not control, certifies what the agent did. Server-side signatures, certifying proxies, neutral third-party receipts. The signing key never touches the agent.

The distinction matters more than it looks.

The student grading their own exam

Layer 1 alone has a structural problem. If the agent controls the signing key, a compromised agent can forge its own identity proofs. It can sign falsified logs. It can claim it did things it never did, or hide things it actually did.

Self-attestation is a student grading their own exam. It works when trust is high and stakes are low. For anything serious (compliance, audit trails, legal evidence) you need a proctor.

Layer 2 gives you the proctor. The attestation comes from something the agent cannot tamper with. A server-side signer. A certifying proxy sitting between the agent and the outside world. A receipt generated by infrastructure the agent never touches.

Why compliance needs both

Under the EU AI Act, Article 12 requires automatic logging for high-risk AI systems. But self-generated logs from the agent itself are weak evidence. If the agent produced the log and signed it with its own key, what stops a compromised agent from producing a clean log?

Tamper-evident records need to come from outside the agent. That is what Layer 2 provides.

You need Layer 1 to know who the agent is. You need Layer 2 to know what it did and that it cannot deny it. Identity plus attestation. Both layers, working together.

The current gap

Most teams building agents today are focused on Layer 1. Identity is well-understood. We have decades of PKI experience to draw from. The patterns are familiar.

Layer 2 is less explored. Tools like ArkForge are building certifying proxies. asqav takes a server-side ML-DSA-65 approach where the signing key stays on the server. These are early but they point in the right direction.

The gap is real. Teams are shipping agents with strong identity and no independent attestation. That is like having a passport with no customs stamps. You can prove who you are but not where you have been.

If you are building agent infrastructure, Layer 2 deserves as much attention as Layer 1. It is harder to get right. It is also where compliance actually lives.