Developer Documentation

Build AI agents with tamper-evident audit trails. AgentTrace gives you immutable hash chains, Ed25519 digital signatures, and compliance-ready reports for EU AI Act Article 12, SOC 2, and ISO 42001.

Introduction

AgentTrace is compliance-grade audit infrastructure for AI agents. Every tool call, LLM invocation, and agent decision is recorded as an immutable event chained together with SHA-256. Any attempt to tamper with a record breaks the chain and is instantly detectable.

Designed for teams deploying AI agents under regulatory frameworks such as the EU AI Act (Article 12), SOC 2, and ISO 42001 — without sacrificing developer velocity.

What you get

  • Immutable hash-chained audit events
  • Ed25519 digital signatures per event
  • Idempotent writes with deduplication keys
  • Multi-tenant isolation via Row Level Security
  • PDF / JSONL compliance reports

Authentication

All requests to the AgentTrace audit API must be authenticated using an API Key. You can create a key from the API Keys page in your dashboard.

Include the key in the Authorization header as a Bearer token:

bash
curl -X POST https:500 italic">//agenttrace-eta.vercel.app/api/audit \
-H 400">"Authorization: Bearer at_live_8f203c6522f081c82d5c9b2a2d2e4d1814cd58f7fc5c818a" \
-H 400">"Content-Type: application/json" \
-d 400">'{"agent_id":"agent-001","session_id":"sess-001","sequence":1,...}'

Never expose your API Key in client-side code or public repositories. Store it securely and rotate it regularly from your dashboard.

SDK Installation

Install the TypeScript SDK to record audit events with just a few lines of code.

bash
npm install @agenttrace/sdk

The SDK handles hash-chain computation, idempotency keys, and authenticated HTTP requests to /api/audit.

Quickstart

Record your first audit event in under a minute. Choose your preferred language below.

Record an agent tool call

Wrap any async agent function with AuditRecorder.wrap. The SDK computes input/output hashes and chains them automatically.

typescript
400">"text-purple-400">import { AuditRecorder } 400">"text-purple-400">from 400">'@agenttrace/sdk';
400">"text-purple-400">const recorder = 400">"text-purple-400">new AuditRecorder({
apiKey: process.env.AGENTTRACE_API_KEY!,
agentId: 400">'weather-agent',
sessionId: 400">'session-001',
});
400">"text-purple-400">const result = 400">"text-purple-400">await recorder.wrap(
400">'get_weather',
{ city: 400">'Paris' },
400">"text-purple-400">async (args) => {
500 italic">// Your existing agent logic
400">"text-purple-400">return { temperature: 22, condition: 400">'sunny', unit: 400">'celsius' };
}
);
console.log(result);

API Reference

POST
/api/audit

Submit a new tamper-evident audit event. Requires a valid API Key in theAuthorization: Bearer header.

URL

https://agenttrace-eta.vercel.app/api/audit

Auth

Authorization: Bearer <API_KEY>

Request Body

json
{
400">"agent_id": 400">"weather-agent",
400">"session_id": 400">"session-001",
400">"sequence": 1,
400">"idempotency_key": 400">"uuid-v4-string",
400">"tool_name": 400">"get_weather",
400">"input_hash": 400">"sha256-hex-string",
400">"output_hash": 400">"sha256-hex-string",
400">"error_code": 400">"text-orange-400">null,
400">"human_override": 400">"text-orange-400">false,
400">"prev_hash": 400">"0000...0000",
400">"current_hash": 400">"sha256-hex-string",
400">"signature": 400">"text-orange-400">null,
400">"key_id": 400">"text-orange-400">null
}
201
401
409

Successful response includes the inserted record with its chain hashes.

json
{
400">"message": 400">"Audit record created",
400">"record": {
400">"id": 400">"fc034d03-9bce-4999-beec-3768c0db85c4",
400">"tenant_id": 400">"tenant_e5953cc127129aa740480631817e3e83",
400">"agent_id": 400">"weather-agent",
400">"session_id": 400">"session-001",
400">"sequence": 1,
400">"idempotency_key": 400">"uuid-v4-string",
400">"tool_name": 400">"get_weather",
400">"input_hash": 400">"sha256-hex-string",
400">"output_hash": 400">"sha256-hex-string",
400">"error_code": 400">"text-orange-400">null,
400">"human_override": 400">"text-orange-400">false,
400">"prev_hash": 400">"0000...0000",
400">"current_hash": 400">"sha256-hex-string",
400">"signature": 400">"text-orange-400">null,
400">"key_id": 400">"a7f8a0cf-08f3-4587-99bb-73b27cfd850f",
400">"created_at": 400">"2026-11-17T01:50:08.046001+00:00"
}
}

401 — Invalid or missing API Key.

409 — Idempotency key already exists; returns the existing record.

AgentTrace provides technical infrastructure only and does not constitute formal legal advice.