Recording Actions
Three ways to record agent actions: record() for explicit recording, wrap() for policy-checked execution, and wrapWithIdentity() for identity-bound recording.
import { Invariance } from '@invariance/sdk';
Overview
`record()` is a low-level method that creates a one-off receipt. `wrap()` is the recommended approach — it checks policies, executes your function, captures the result or error, and creates a signed receipt in one call.
`wrapWithIdentity()` goes further: it derives a unique Ed25519 keypair for the specified identity using HKDF, creates a dedicated session, and signs receipts with the derived key. This is ideal for multi-agent systems where each agent needs its own cryptographic identity.
Important Notes
wrap() handles policy checking, execution, error capture, and receipt creation in a single call.
Quick Example
// 1. record() — explicit, low-level
const receipt1 = await inv.record({
agent: 'bot', action: 'search',
input: { query: 'hello' }, output: { results: 5 },
});
// 2. wrap() — policy check + execute + record
const { result, receipt: receipt2 } = await inv.wrap(
{ agent: 'bot', action: 'transfer', input: { to: '0x...', amount: '1.0' } },
() => doTransfer(),
);
// 3. wrapWithIdentity() — identity-bound recording
const { result: r3, receipt: receipt3, identity } = await inv.wrapWithIdentity(
() => runComplianceCheck(),
{ identity: 'acme/compliance-agent', action: 'audit', input: { target: 'tx-123' } },
);
Type Definitions
Action
interface Action {
agent?: string;
action: string;
input: Record<string, unknown>;
output?: Record<string, unknown>;
error?: string;
tags?: string[];
metadata?: Record<string, unknown>;
}
An action performed by an agent.
API Reference
record
Record a single action as a one-off receipt.
async record(action: Action): Promise<Receipt>
Parameters
actionActionThe action to record — must include agent
ReturnsPromise<Receipt>
wrap
Policy check, execute, record. The primary method for recording actions with enforcement.
async wrap<T>(action: Omit<Action, "output" | "error">, fn: () => T | Promise<T>): Promise<{ result: T; receipt: Receipt }>
Parameters
actionActionAction metadata (agent, action name, input)
fn() => T | Promise<T>The function to execute
ReturnsPromise<{ result: T; receipt: Receipt }>
wrapWithIdentity
Execute a function with a derived identity. Derives a unique Ed25519 keypair using HKDF.
async wrapWithIdentity<T>(fn: () => T | Promise<T>, opts: { identity: string; action: string; input: Record<string, unknown> }): Promise<{ result: T; receipt: Receipt; identity: AgentIdentity }>
Parameters
fn() => T | Promise<T>The function to execute
opts.identitystringIdentity string, e.g. "acme/compliance-agent"
opts.actionstringAction name
opts.inputRecord<string, unknown>Action input data
ReturnsPromise<{ result: T; receipt: Receipt; identity: AgentIdentity }>
Use Cases
- Use wrap() as the default for all agent actions — combines policy enforcement with audit trail
- Use record() for logging non-executable events (received messages, observations)
- Use wrapWithIdentity() in multi-agent systems where each agent needs cryptographic identity separation
- Capture errors automatically — wrap() records the error message in the receipt when fn() throws