Forem: João André Gomes Marques

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.

Add governance to DSPy pipelines

João André Gomes Marques — Sun, 12 Apr 2026 07:21:57 +0000

DSPy pipelines are interesting because they optimize themselves. You write modules, the optimizer rewrites your prompts, and the final program runs in loops making LLM calls and tool invocations without you watching each step. That's the whole point.

But it also means you can lose track of what happened. A pipeline that ran overnight. Which LLM calls did it make? What tools did it invoke? If it produced a weird output at 4am, good luck reconstructing the chain of events from logs alone.

Two lines after your imports

pip install asqav[dspy]

import asqav
import dspy
from asqav.extras.dspy import AsqavDSPyCallback

asqav.init(api_key="...")
dspy.configure(callbacks=[AsqavDSPyCallback(agent_name="my-agent")])

That's the entire setup. Once that callback is registered, every operation in your DSPy pipeline gets signed automatically.

What gets signed

The callback hooks into DSPy's event system and signs six event types:

dspy.module.start / dspy.module.end - when a module begins and finishes execution
dspy.lm.start / dspy.lm.end - every LLM call, with the prompt going in and completion coming out
dspy.tool.start / dspy.tool.end - any tool invocations the pipeline makes

Each event gets an ML-DSA-65 signature (FIPS 204). The signing happens server-side so the SDK is just a thin API client. You end up with a cryptographic audit trail of every operation your pipeline performed.

Why this fits DSPy well

DSPy programs are compiled. After optimization, the prompts and routing can look nothing like what you originally wrote. That's great for performance but terrible for observability. You need to know what the optimized program actually did, not what you think it should have done.

The callback sits at the execution layer, so it captures what really happens at runtime. Not the source code, not the original prompts, but the actual calls the compiled program makes.

Also, DSPy pipelines tend to run in loops during optimization. That means lots of LLM calls, lots of tool invocations. Having a signed record of each one lets you audit the optimization process itself, not just the final output.

Fail-open design

Same as the other asqav integrations. If the signing service has an issue, the callback logs a warning and your pipeline keeps running. Governance doesn't become a bottleneck or a failure point. Your DSPy program doesn't care whether the signature succeeded or not.

Getting started

The SDK is MIT-licensed: github.com/jagmarques/asqav-sdk

Grab an API key at asqav.com/dashboard, add those two lines after your imports, and your next pipeline run will have a complete signed audit trail. No changes to your modules, no changes to your tools.

Why your AI agent needs a .well-known discovery endpoint

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

You know how websites publish /.well-known/security.txt so security researchers can find the right contact? RFC 9116 made that a standard. Simple file, fixed location, machine-readable. It works because everyone agrees where to look.

AI agents need something similar. Not for security contacts, for governance discovery.

The problem

Say you're integrating with an AI service. You want to know: does this agent sign its actions? What algorithm? Where do I verify a signature? What capabilities does the governance layer support?

Right now you'd dig through docs, maybe find an API reference, maybe email someone. There's no standard place to look.

The pattern

A /.well-known/governance.json file at a predictable URL. Any client or auditor can fetch it and immediately understand what governance is available.

Here's what goes in it:

{
  "name": "your-service",
  "version": "1",
  "endpoints": {
    "sign": "https://api.example.com/v1/agents/{agent_id}/sign",
    "verify": "https://api.example.com/v1/verify/{signature_id}",
    "agents": "https://api.example.com/v1/agents"
  },
  "algorithms": ["ml-dsa-44", "ml-dsa-65", "ml-dsa-87"],
  "capabilities": [
    "sign",
    "verify",
    "delegation",
    "policy_enforcement",
    "audit_export_csv"
  ],
  "auth": {
    "type": "api_key",
    "header": "X-API-Key"
  },
  "license": "MIT"
}

The key sections:

endpoints - where to sign actions, verify signatures, manage agents
algorithms - which cryptographic algorithms are supported (ML-DSA is the FIPS 204 post-quantum family)
capabilities - what the governance layer can actually do
auth - how to authenticate

Why this matters for interoperability

If every AI governance provider publishes this file at the same path, tooling can auto-discover it. CI/CD pipelines can check if governance is configured. Auditors can programmatically verify that an agent's governance claims match reality.

It's the same reason robots.txt works. Convention over configuration. You don't need a registry or a discovery service. Just a file at a known path.

A live example

We publish ours at asqav.com/.well-known/governance.json. It includes endpoints, supported algorithms, integration list, and links to docs. Anyone can fetch it right now.

But this isn't an asqav-specific idea. Any project doing AI governance could publish the same file. The schema is straightforward. Adapt it to whatever your service provides.

Adopting this yourself

If you run an AI governance service, or even just an agent platform with audit capabilities:

Create /.well-known/governance.json on your domain
List your endpoints, algorithms, and capabilities
Keep it updated when your API changes

No spec to implement. No committee to join. Just a JSON file at a URL that makes sense.

The more projects that do this, the easier it gets to build tooling around AI governance discovery. And that's the whole point, making governance something you can verify programmatically instead of taking someone's word for it.

Add governance to Hugging Face smolagents in 4 lines

João André Gomes Marques — Sun, 12 Apr 2026 07:20:11 +0000

I was building an agent with Hugging Face's smolagents last month and hit a problem that kept bugging me. The agent ran tools, made decisions, called APIs, and I had zero record of what happened. If something went wrong, I'd be guessing.

smolagents gives you a clean way to build tool-calling agents. But once a tool runs, there's no audit trail. No proof of what was called, when, or what it returned. For hobby projects, fine. For anything touching production data, that's a gap.

Here's how I plugged it with asqav in 4 lines.

The setup

pip install asqav[smolagents]

from asqav.extras.smolagents import AsqavSmolagentsHook

hook = AsqavSmolagentsHook(agent_name="my-smolagent")
signed_tool = hook.wrap_tool(my_tool)

That's it. wrap_tool takes your existing tool and returns a wrapped version that signs three events:

tool:start - when the tool is called, with its input parameters
tool:end - when it completes, with the output
tool:error - if it throws, with the exception details

Each event gets a cryptographic signature using ML-DSA-65 (that's FIPS 204, the post-quantum standard). Signatures happen server-side so the SDK stays thin. You get a tamper-evident log of every tool execution your agent performed.

What I like about the design

It's fail-open. If the signing service is down or something goes wrong with the signature, it logs a warning and moves on. Your agent keeps working. Governance shouldn't be a single point of failure for your pipeline.

You also don't need to change your tool's code. The hook wraps the tool at the boundary. Your tool function stays exactly the same. Swap it in, swap it out, your logic doesn't care.

When this matters

If you're running smolagents that touch external APIs, databases, or anything with side effects, you probably want to know what happened after the fact. Debugging is one thing. But if you need to show an auditor or a compliance team what your agent did last Tuesday at 3am, "I think it worked fine" doesn't cut it.

The signed events give you a verifiable chain. Each signature can be independently verified, and the log can't be quietly edited after the fact.

Try it

The SDK is open source: github.com/jagmarques/asqav-sdk

Grab an API key from asqav.com/dashboard and wrap your first tool. Four lines, and you've got a governance layer that doesn't get in the way.

SDK v0.2.9: Output Verification, Attestations, Preflight and Budgets

João André Gomes Marques — Fri, 10 Apr 2026 18:24:31 +0000

v0.2.9 is out on PyPI. Four new things, all driven by what people asked for after shipping agents to production: prove the output wasn't swapped, hand a customer a document they can verify themselves, check everything before you run, and stop agents burning through a budget.

Install or upgrade:

pip install --upgrade asqav

Output verification

Signing that an action happened is one thing. Proving the output you see now is the same output the agent produced is another. sign_output binds a hash of the result to a hash of the input, then verify_output checks both later.

import asqav

agent = asqav.Agent.create("research-bot")

query = {"question": "latest NIST PQC guidance"}
result = {"answer": "FIPS 203, 204, 205 finalized in 2024"}

sig = agent.sign_output(
    action_type="tool:search",
    input_hash=asqav._hash_value(query),
    output=result,
)

# Later, or on another machine:
check = asqav.verify_output(sig.signature_id, result)
assert check["verified"]  # signature valid AND output matches

If anyone changes a character in result before verification, output_matches comes back false. If the signature itself was tampered with, signature_valid comes back false. You get both signals separately so you can tell what went wrong.

Portable attestations

You often need to show someone outside your team that an agent did what it was supposed to, without giving them access to your Asqav account. generate_attestation builds a self-contained document with the agent's public key, a session summary, and a signature over the whole thing. verify_attestation checks it.

agent = asqav.Agent.create("contract-reviewer")
session = agent.start_session()
# ... run the agent, sign actions ...
agent.end_session()

doc = asqav.generate_attestation(
    agent.agent_id,
    session_id=session.session_id,
)

# Hand doc.json to an auditor. They run:
result = asqav.verify_attestation(doc)
print(result["valid"], result["all_valid"], result["signatures_checked"])

The attestation carries its own hash and signature, plus every signature ID from the session. The auditor doesn't need your keys. They just need the SDK and the document.

Pre-flight checks

Before v0.2.9 you had to call three things to know if an agent was cleared: status, policy list, and sometimes certificate. preflight does it in one call and tells you why if it says no.

agent = asqav.Agent.get("agt_abc123")

check = agent.preflight("api:transfer")
if not check.cleared:
    print("blocked:", check.reasons)
    return

# Agent is active and policy allows the action. Proceed.

It returns cleared, agent_active, policy_allowed, and a list of reasons. If a sub-check errors, the reason is noted but the agent isn't blocked on infrastructure hiccups. Run it at the top of any sensitive action and you catch revoked agents and policy blocks before you waste an LLM call.

Budget tracking

Agents that call paid APIs need a ceiling. BudgetTracker enforces the limit client-side and signs every spend entry so the trail is tamper-evident.

agent = asqav.Agent.create("data-enricher")
budget = asqav.BudgetTracker(agent, limit=10.0, currency="USD")

decision = budget.check(estimated_cost=0.25)
if not decision.allowed:
    raise RuntimeError(decision.reason)  # "budget_exhausted"

# ... call OpenAI, measure actual cost ...
budget.record("api:openai", actual_cost=0.23, context={"model": "gpt-4"})

print(budget.status())
# {'limit': 10.0, 'currency': 'USD', 'spend': 0.23, 'remaining': 9.77, 'records': 1}

Every record call writes a signed entry through the agent's key. You can replay the trail against the verification endpoint at any point and prove exactly where the money went. Negative, NaN, and infinite costs all get rejected. The check fails closed.

Why these four

These are the gaps people kept hitting. Signing the call isn't enough if the output can be swapped. Signatures aren't useful if you can't hand one to an external reviewer. Status and policy checks want to be one call. Budget caps need to be real, not a comment in a README.

Full changelog and source on GitHub. Docs at asqav.com/docs. If something doesn't work the way you expect, open an issue.