DEV Community

Himanshu Tripathi
Himanshu Tripathi

Posted on

Identity for ai agents

#agents #ai #monitoring #tutorial

How to Add an Audit Trail to Your AI Agent in 3 Lines of Code

If you're building with AI agents — whether using LangChain, Claude, GPT-4, AutoGen, or CrewAI — you've probably asked yourself at some point: what exactly did my agent do?

The honest answer for most developers right now is: nothing. No record. No proof. No way to know.

This post covers why that's a problem, what it costs you in practice, and how to fix it in under 5 minutes.

The Problem: AI Agents Run Blind

When a traditional application makes a database write or an API call, you have logs. You know what happened, when, and why.

AI agents are different. They reason, decide, and act — often across multiple steps, multiple tools, and multiple external services. But most agent frameworks give you:

  • Console output (disappears when the process ends)
  • LLM token logs (shows inputs/outputs, not decisions)
  • Nothing at all

This creates three real problems:

1. Runaway costs
An agent stuck in a retry loop at 2am has nothing stopping it from making 10,000 API calls before anyone notices. Without a spending limit enforced at the action level, your bill arrives before your alert does.

2. No legal defensibility
If an agent sends an unauthorized email, makes a purchase it shouldn't have, or accesses data outside its scope — you have no cryptographic proof of what it was authorized to do. The EU AI Act (enforcement: August 2026) explicitly requires high-risk AI systems to maintain logs of decisions. "The LLM decided" is not a compliance strategy.

3. No debugging
When an agent behaves unexpectedly in production, the first question is always: what did it actually decide to do, and why? Without a permanent audit trail, you're guessing.

What a Proper Audit Trail Looks Like

A proper audit trail for an AI agent should answer these questions for every action:

  • What action was attempted (type, target domain, amount)
  • What verdict was returned (approved, blocked, escalated)
  • Why the verdict was given (which policy rule fired)
  • When it happened (tamper-proof timestamp)
  • Who authorized it (cryptographic signature)

This is exactly what AIVIL provides.

Adding an Audit Trail in 3 Lines 

npm install aivil
Enter fullscreen mode Exit fullscreen mode 
const AIVIL = require('aivil')

const aivil = new AIVIL({ apiKey: process.env.AIVIL_API_KEY })

// Step 1: Create your agent once
const { agent } = await aivil.getOrCreate({
  name: "Procurement Agent",
  role: "Procurement Specialist",
  owner: "Acme Corp",
  jurisdiction: "Delaware_USA",
  policy: {
    spending_limit: 100,              // blocks purchases over $100
    requires_human_signoff_over: 50,  // escalates above $50
    blocked_topics: ["gambling", "adult", "illegal"],
    allowed_topics: ["vendors", "pricing", "procurement"],
  }
})

// Step 2: Audit before every action
const verdict = await aivil.audit(agent.id, {
  type: "purchase",
  amount: 30,
  domain: "openai.com",
  description: "Buy API credits for data processing"
})

// Step 3: Act on the verdict
if (verdict.status === "APPROVED")  executeAction()
if (verdict.status === "ESCALATE")  notifyHuman(verdict.reason)
if (verdict.status === "BLOCKED")   logAndStop(verdict.reason)
Enter fullscreen mode Exit fullscreen mode

That's it. Every decision is now:

  • Logged permanently to a tamper-proof audit trail
  • HMAC-signed with a server secret
  • Visible in real time on a live dashboard
  • Defensible in a compliance audit

Try It Without Signing Up

You can try AIVIL right now with no account:

const aivil = new AIVIL({ apiKey: "aivil_demo" })

const verdict = await aivil.audit("AGT-DEMO001", {
  type: "purchase",
  amount: 200,
  domain: "casino.gambling",
  description: "Buy credits"
})

console.log(verdict.status)  // BLOCKED
console.log(verdict.reason)  // Domain "casino.gambling" is restricted by policy.
Enter fullscreen mode Exit fullscreen mode

The demo key runs against a real policy engine. No credit card, no signup, no friction.

What Happens When an Action is Blocked 

{
  "status": "BLOCKED",
  "reason": "Domain \"casino.gambling\" is restricted by policy.",
  "flags": ["RESTRICTED_DOMAIN"],
  "trust_score": 68,
  "agent_registry": "https://aivildev.com/agent/AGT-DEMO001",
  "signature": "b2c3d4e5f6a1...",
  "audit_id": "bb6461a3-2f17-4fcf-a4cc-9f77e5756b5c",
  "timestamp": "2026-06-03T10:24:06.000Z"
}
Enter fullscreen mode Exit fullscreen mode

Every verdict includes:

  • flags — exactly which policy rule fired
  • trust_score — the agent's running behavior score
  • signature — HMAC-SHA256 proof the verdict was issued by your server
  • audit_id — permanent reference for compliance queries
  • agent_registry — public URL anyone can visit to verify the agent

Integrating With Your Existing Agent Framework

LangChain 

// Before executing any tool
const verdict = await aivil.audit(agent.id, {
  type: tool.name,
  amount: tool.args.amount || 0,
  domain: tool.args.url ? new URL(tool.args.url).hostname : "",
  description: tool.args.query || tool.description
})

if (verdict.status !== "APPROVED") {
  throw new Error(`AIVIL blocked: ${verdict.reason}`)
}

// Safe to execute
return await tool.execute(tool.args)
Enter fullscreen mode Exit fullscreen mode

OpenAI Function Calling 

const toolCall = response.choices[0].message.tool_calls?.[0]

if (toolCall) {
  const verdict = await aivil.audit(agent.id, {
    type: toolCall.function.name,
    amount: JSON.parse(toolCall.function.arguments).amount || 0,
    description: toolCall.function.arguments
  })

  if (verdict.status === "APPROVED") executeTool(toolCall)
  else console.log("AIVIL blocked:", verdict.reason)
}
Enter fullscreen mode Exit fullscreen mode

Claude MCP (Zero Code)

Add one line to your Claude Desktop config:

{
  "mcpServers": {
    "aivil": { "url": "https://mcp.aivildev.com/mcp" }
  }
}
Enter fullscreen mode Exit fullscreen mode

Claude will automatically audit every action before executing. No code changes required.

EU AI Act Compliance

The EU AI Act's high-risk AI obligations take effect August 2026. Article 12 explicitly requires:

"Logging capabilities to ensure traceability of the AI system's output"

AIVIL's cryptographic audit trail — HMAC-signed, immutable, permanently stored — directly addresses this requirement. Every audit decision includes a verifiable signature that proves:

  1. The agent was authorized to act
  2. The action was within its defined policy
  3. The decision was made at a specific timestamp
  4. The record has not been altered since

For teams building agents that touch financial data, personal data, or automated decision-making — this is not optional after August 2026.

What AIVIL Doesn't Do

To be clear about scope:

  • AIVIL does not replace your LLM — it wraps your agent's actions
  • AIVIL does not guarantee your agent behaves correctly — it enforces the policy you define
  • AIVIL is not a silver bullet — it's a compliance and observability layer

You are still responsible for defining sensible policies. AIVIL enforces them.

Getting Started 

npm install aivil
Enter fullscreen mode Exit fullscreen mode

Free plan: 5 agents, 1,000 audits/month, no credit card.

Summary

Without AIVIL With AIVIL
No record of agent decisions Every decision logged permanently
No spending controls Hard limits enforced per action
No legal defensibility Cryptographic proof of authorization
Debugging by guessing Full audit trail with flags and reasons
EU AI Act liability Compliant audit trail from day one

If you're building AI agents that interact with real systems — APIs, databases, emails, purchases — add an audit trail before you need one.

It takes 3 lines of code. It's free. And it might save you from a very expensive conversation later.

AIVIL is open source under AGPL-3.0. Try it at aivildev.com or install directly with npm install aivil.

Top comments (0)