Feature: Agent Action Receipt (AAR) middleware for provable tool calls

[Cyberweasel777]

Problem

The Vercel AI SDK powers agent tool calls, structured outputs, and multi-step reasoning — but there's no built-in mechanism for cryptographically proving what an agent did. As AI moves from chat into consequential actions (payments, data mutations, API calls), unsigned execution logs aren't sufficient for auditability.

Proposal: Agent Action Receipt (AAR) Support

AAR is a lightweight open standard for Ed25519-signed proof of agent actions:

• What — action name, scope, input/output SHA-256 hashes
• Who — agent identity, principal (user/system that authorized it)
• When — ISO 8601 timestamp
• Proof — Ed25519 detached signature, offline-verifiable

The SDK is <10KB, zero external dependencies, works in Edge Runtime.

Integration surface

Natural fit as a streamText / generateText middleware or experimental_telemetry extension:

import { generateText } from "ai";
import { withAAR } from "botindex-aar/vercel";

const result = await generateText({
  model: openai("gpt-4"),
  prompt: "Analyze this contract",
  experimental_telemetry: withAAR({ agent: "contract-analyzer" }),
});
// result.receipt → signed AAR receipt

Every tool call gets a receipt. Receipts chain for multi-step provenance.

Resources

• Spec: https://github.com/Cyberweasel777/agent-action-receipt-spec
• npm: https://www.npmjs.com/package/botindex-aar
• Landing: https://aar.botindex.dev
• Active in: crewAI, FINOS AI Governance, AWS Agent Squad

[Sigmabrogz]

Hi! I'd like to work on this. My understanding is that the AI SDK needs a built-in mechanism to generate cryptographically verifiable Agent Action Receipts (AAR) for agent tool calls and structured outputs. I'm planning to fix it by building an AAR middleware extension hooking into experimental_telemetry or the generateText/streamText lifecycle, ensuring each action produces an offline-verifiable Ed25519-signed receipt containing action metadata and SHA-256 hashes. Does this approach sound good?

[jagmarques]

We've been running this pattern in production. The receipt needs three things to actually hold up for compliance: the payload hash, a chained signature linking to the previous action (so you can't cherry-pick which receipts to show), and the policy evaluation result (did a rule allow or block this). Without the chain, individual receipts are easy to omit. Built this into asqav if you want a reference for the signing flow.

[piiiico]

We've shipped an external package that takes a different angle on this: behavioral telemetry rather than receipts.

@agentlair/vercel-ai hooks into experimental_telemetry and forwards tool calls, completions, errors, and token counts to AgentLair's behavioral event API. The events feed a trust score algorithm — agents build verifiable track records over time.

import { createAgentLairExporter } from '@agentlair/vercel-ai';

const agentlair = createAgentLairExporter({
  apiKey: process.env.AGENTLAIR_API_KEY!,
  agentId: 'my-agent',
});

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Hello',
  experimental_telemetry: {
    isEnabled: true,
    tracer: agentlair,
  },
});

Zero deps, works with any model provider. The trust profile is public and embeddable — useful for multi-agent systems where one agent needs to evaluate another before delegating work.

Different from the AAR proposal here (which focuses on per-action cryptographic signatures), but solves a related problem: "should I trust this agent's output?"

[piiiico]

For LangChain.js / LangGraph users: @agentlair/langchain ships the same behavioral telemetry via a callback handler.

import { AgentLairCallbackHandler, injectAat } from '@agentlair/langchain';

const handler = new AgentLairCallbackHandler({ apiKey: process.env.AGENTLAIR_API_KEY, agentId: 'my-agent' });
await agent.invoke({ messages }, injectAat(aat.token, { callbacks: [handler] }));

Captures tool_start/end/error, llm_start/end, and agent_action events. Same trust profile as @agentlair/vercel-ai. Mixed stacks (some chains in LangGraph, some in Vercel AI SDK) write to the same agent identity.

Zero hard deps. @langchain/core is an optional peer.

[tomjwxf]

I opened a small example PR showing this pattern using the AI SDK's existing typed tool-execution callbacks:

PR: #15754

The example uses onToolExecutionStart and onToolExecutionEnd to emit a hash-chained receipt before and after each tool execution. It records tool name, tool call ID, validated input digest, output/error digest, duration, previous receipt hash, and a signature.

I intentionally kept the example dependency-free with HMAC-SHA256 so it fits the examples repo. For public/offline third-party verification, the same receipt shape should swap the signer to Ed25519 and publish the verification key.

The key point: the current callback surface is already enough to demonstrate AAR-style receipts for tool calls; the remaining question is whether the SDK should eventually expose a first-class helper or keep this as an integration pattern.

[piiiico]

Nice work — using the typed callbacks as the interception point rather than wrapping tool definitions is the right instinct. Instrumentation stays decoupled from business logic, and the receipt shape is clean.

On the Ed25519 note: that's exactly what AgentLair's agent identity tokens use — Ed25519 JWTs, verifiable offline via JWKS. The practical difference from HMAC is key distribution: HMAC proves consistency within a session, Ed25519 lets a third party verify without a shared secret. If you wanted to extend your example toward the full offline-verifiable path, the AAT is one way to supply the signing keypair without managing key distribution yourself.

Your framing of the SDK question is right. The callback surface is already sufficient; the open question is whether teams wire it correctly in practice. A lightweight middleware helper — even just in the examples repo or a separate package — would close that gap without adding SDK complexity.

[piiiico]

@jagmarques the requirements you laid out — hash chain to prevent cherry-picking, policy eval result embedded, payload hash — are the right bar. Most implementations stop at signing individual events.

AgentLair provides the key infrastructure: each agent gets a persistent Ed25519 identity, verifiable offline via JWKS (agentlair.dev/.well-known/jwks.json, EdDSA key live). No shared secret needed for third-party verification. @agentlair/vercel-ai hooks into onToolExecutionStart/onToolExecutionEnd — same surface tomjwxf used in #15754 — and forwards events to cross-session storage keyed to agent identity. The chain and policy result layer on top of the events you're already collecting.

The policy eval field in asqav — is that an allow/deny from a rule engine, or something at the model level? Would be useful to support that shape natively.

Happy to give you a free trial key if you want to compare it against what you have.

[rpelevin]

I would split the receipt into two related records: pre-action authority and post-action execution.

The AAR after a tool call can prove what happened, but by itself it does not prove the call was allowed before execution. For consequential tools, the middleware probably needs to preserve both:

• a stable action id
• tool name and call id
• canonical input digest
• actor / agent / session identity
• policy or approval reference if one existed
• approval decision and decided_by for gated tools
• execution start/end timestamps
• result digest or error class
• prior receipt hash for chain continuity

The useful middleware shape may be a before/after pair: one hook mints or links the pre-action decision, the second hook seals the execution outcome.

That keeps auditability from turning into "the agent signed its own after-the-fact log." The receipt should say not only what ran, but whether the runtime had authority to run that exact call.

Useful regressions: an execution receipt without a required approval ref is flagged incomplete; changing input after approval breaks the digest match; a failed tool still emits an outcome receipt; and removing one receipt from a multi-step chain is detectable.

[piiiico]

We shipped this split in @agentlair/audit-logger — beginAction mints the pre-action record (inputDigest, actorId, policyRef, approvalDecision, decidedBy), endAction seals the post-action (outputDigest or errorClass, execution timestamps, previousReceiptHash linking back to the pre-action sans signature).

One thing your comment surfaces that we haven't handled: a pre-action with approvalDecision: 'denied' currently doesn't require a corresponding post-action. That breaks the "execution receipt without a required approval ref is flagged incomplete" regression — from the other direction. A denied pre-action with no sealed post-action is indistinguishable from a dropped record. Probably needs a phase: 'denied' post-action or a mandatory endAction even on denial.

[rpelevin]

Yes, I think the clean version is: endAction is mandatory for every beginAction, but the terminal record should not imply execution.

In the docs/API language, I would probably describe the second record as a terminal receipt rather than only a post-action receipt:

• phase: executed | failed | denied | expired | cancelled
• same actionId
• same canonical inputDigest
• same policyRef, approvalDecision, and decidedBy
• terminal timestamp and terminal reason
• resultDigest or errorClass only when execution actually started
• previous receipt hash linking back to the pre-action record

The invariant becomes: every proposed action attempt closes exactly once, but only phase: executed proves the tool actually ran.

That makes a denied call first-class audit evidence instead of an absence. It also gives you useful regressions:

• denied beginAction without a terminal receipt is incomplete
• phase: executed after approvalDecision: denied is invalid
• changing input between the pre-action record and terminal receipt breaks the digest match
• omitted denials break chain continuity

So the audit trail can distinguish "blocked intentionally" from "logger dropped the event" without inventing a fake execution receipt.

[piiiico]

Terminal-receipt is the right framing. Naming the closing record by phase makes denial first-class evidence, not an absence. v0.3 will adopt phase: executed | failed | denied | expired | cancelled, require endAction per beginAction, and refuse to seal executed over a denied pre-action at sign time. That gets regression #2 before verification. The other three fall out of previousReceiptHash over canonical pre-action including inputDigest, once denied terminals join the chain.

Open question on phase: 'expired': is the terminal timestamp the policy deadline, or when the logger noticed expiry? Deadline is reconstructable from policyRef but ignores logger crash. Noticed-at matches "the signature is the logger's claim, not the policy's" but needs a watchdog. I'd lean noticed-at.

[rpelevin]

I would use noticed-at as the terminal receipt timestamp, and keep the policy deadline as a separate value.

Reason: the terminal receipt is the logger's signed claim. It can truthfully claim "I observed/closed this action as expired at T", but it should not pretend the logger signed at the policy deadline if the logger only noticed later.

A concrete shape could be:

• phase: expired
• actionId
• previousReceiptHash
• expiresAt from the pre-action/policy record
• closedAt or observedAt as the signed terminal timestamp
• closedBy: watchdog | recovery | endAction
• closeReason: policy_deadline

Then verification can check two different things:

• did the action's authority window expire? closedAt >= expiresAt
• did the logger close the attempt cleanly? terminal receipt exists, links to the pre-action record, and no executed terminal exists for the same actionId

That also makes logger crash behavior explicit. If the watchdog/recovery path closes it later, the receipt says that honestly: expired by policy at expiresAt, observed/closed by the logger at closedAt.

So I would not set the signed terminal timestamp to the policy deadline. I would sign the observation time, and carry the policy deadline as the reason/evidence for why the terminal phase is expired.

[piiiico]

Shipped as @agentlair/audit-logger@0.3.0 — proof the terminal-receipt design is actionable today.

What landed:

• Phase enum: executed | failed | denied | expired | cancelled
• terminalAt always present — for expired, this is the logger's observation timestamp, not the policy deadline (matching your latest point exactly). terminalReason can carry the policy deadline or closeReason as evidence.
• Sign-time invariant: endAction() throws if phase: 'executed' and preAction.approvalDecision: 'denied' — executed-over-denied is structurally impossible, not just undocumented
• verifyChain() now returns incomplete when a pre-action has no terminal receipt (denial as first-class evidence, not an absence)
• Denied terminals participate in the hash chain — omitting one breaks the successor's hash

The expiresAt field you sketched (carry the policy deadline alongside terminalAt) isn't in v0.3 yet — that's the natural v0.4 extension once expiry handling is verified in practice.