Audit Schema Implementation Guide: Transaction-Level Agent Auditing with @harpd/agent-transaction-audit-schema

Core Answer (≈100 words)
To create a reliable audit schema for AI agents, adopt the open‑source @harpd/agent-transaction-audit-schema JSON definition, which captures the essential attributes of each transaction — who initiated it, which agent processed it, the model used, cost incurred, and the exact timestamp. By wiring this schema into your logging pipeline, you gain a consistent agent audit trail that supports compliance checks, cost allocation, and debugging. Pair the schema with Harpd’s Spend Control product to enforce budget caps in real time, turning raw logs into actionable guardrails for autonomous spending.

---

Why transaction-level audit schemas matter for AI agent governance

AI agents are increasingly given autonomy over resources, data access, and financial transactions. Without a granular agent audit trail, organizations cannot prove who spent what, why, or under which model. A well‑designed transaction-level auditing mechanism provides three critical benefits:

1. Traceability – Every spend event is linked to a specific actor and model, enabling root‑cause analysis when anomalies appear.
2. Compliance – Regulators and internal auditors can verify that usage complies with policy by checking the recorded JSON schema for agent audits.
3. Observability – Real‑time visibility into agent behavior supports proactive monitoring and alerts.

When multiple teams or microservices interact with agents, a shared schema eliminates integration friction, ensuring that logs from disparate sources can be aggregated and queried uniformly. This standardisation is the foundation for trustworthy AI agent observability.

---

Anatomy of @harpd/agent-transaction-audit-schema: fields for who, which agent, model, cost, and timestamp

The @harpd/agent-transaction-audit-schema is a concise JSON schema that defines the following mandatory fields:

Field	Description	Example
actor	Identity of the entity that triggered the transaction (user ID, service account, etc.)	"actor":"user-12345"
agent_name	Human‑readable name of the agent that processed the transaction	"agent_name":"data‑fetcher‑v2"
model	Identifier of the underlying LLM or inference engine used	"model":"gpt‑4‑turbo"
cost_usd	Monetary cost of the transaction in USD	"cost_usd":0.0275
timestamp	ISO‑8601 UTC time when the transaction completed	"timestamp":"2025-09-24T14:32:10Z"
metadata	Optional free‑form bag for extra context (e.g., request payload hash)	"metadata":{"request_id":"req-9876"}

Key takeaway: By enforcing this structure across all logging points, you guarantee that every transaction can be parsed, indexed, and audited without custom parsing logic.

---

Step‑by‑step: integrating the schema into your agent logging pipeline

1. Install the package

   npm install @harpd/agent-transaction-audit-schema

2. Create a logger wrapper that formats each outgoing transaction into a JSON object matching the schema.

   const { TransactionAudit } = require('@harpd/agent-transaction-audit-schema');
   
   function logTransaction(event) {
     const audit = new TransactionAudit({
       actor: event.initiator,
       agent_name: process.env.AGENT_NAME,
       model: event.model,
       cost_usd: event.cost,
       timestamp: new Date().toISOString(),
       metadata: event.metadata,
     });
     console.log(JSON.stringify(audit.toJSON()));
   }

3. Emit the JSON to your central logging system (e.g., Elasticsearch, Loki, or CloudWatch).

4. Validate each entry against the schema using a JSON‑Schema validator to catch malformed records early.

5. Forward the validated record to Harpd’s Spend Control service for real‑time budget enforcement (see next section).

Best practice: Keep the wrapper stateless so that each log line can be processed independently, which simplifies scaling and replay.

---

Real-world use cases: compliance, cost allocation, and debugging multi‑agent systems

Compliance

Regulatory frameworks such as GDPR, SOC 2, and industry‑specific spend policies require proof of who accessed data and how much it cost. A standardized audit schema lets you generate compliance reports with a single query:

SELECT agent_name, SUM(cost_usd) AS total_spend
FROM audit_logs
WHERE timestamp BETWEEN '2025-01-01' AND '2
## Related reading
- [The open-source example project: an agent that pays for its own data](https://harpd.com/blog/open-source-example-project/)
- [x402 vs Mastercard Agent Pay vs Google AP2: which agent payment protocol should you use?](https://harpd.com/blog/x402-vs-mpp-vs-ap2/)
- [Agent transaction audit: a schema you can copy](https://harpd.com/blog/agent-transaction-audit-schema/)