# Hcs AI Audit Trail

> Build tamper-evident AI agent audit logs using HCS — JSON payloads for decisions, LangChain/LangGraph/AutoGen callback hooks, Mirror Node dashboards, nanosecond ordering, GDPR-aware redaction fields. Use when user mentions AI audit, agent logging, LangChain Hedera, decision trace, compliance logging for LLM, HCS for ML ops, or GDPR AI records.

- Skill: `evaluris-solutions/hcs-ai-audit-trail` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add evaluris-solutions/hcs-ai-audit-trail`
- Raw SKILL.md: https://api.skillmd.com/api/skills/evaluris-solutions/hcs-ai-audit-trail/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Evaluris-Solutions (https://skillmd.com/u/evaluris-solutions)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/evaluris-solutions/hcs-ai-audit-trail

---


## Overview

Pair **AI orchestration frameworks** with **HCS topics** so each model/tool decision lands in an immutable, ordered stream. Use concise JSON envelopes (see [references/decision-log-schema.md](references/decision-log-schema.md)) and offload heavy payloads to IPFS/HTTPS with content hashes inside HCS messages.

## When to use this skill

- Proving **what the agent decided** and **when** relative to on-chain/off-chain events.
- Designing **GDPR** workflows where personal data never enters plaintext public topics.

## Prerequisites

- Running HCS topic + credentials from `hedera-environment-setup`.
- Understanding that **public testnets are public** — never log secrets or raw PII.

## Workflow

1. **Define schema** — adopt JSON Schema in references; version `schema_version` field per deployment.

2. **Instrument framework**
   - **LangChain** — custom callback handler serializes `on_chain_start`, `on_tool_end`, etc.
   - **LangGraph** — wrap node transitions.
   - **AutoGen** — hook reply events.

   Starter: [scripts/langchain-hcs-callback.js](scripts/langchain-hcs-callback.js) (pattern-level sample).

3. **Publish** — `TopicMessageSubmitTransaction` per event or batch in chunk framing when necessary.

4. **Visualize** — query Mirror REST chronologically for dashboards ([scripts/query-audit-trail.js](scripts/query-audit-trail.js)).

5. **GDPR** — hash identifiers, store DPIA references off-chain; see [references/gdpr-considerations.md](references/gdpr-considerations.md).

## Examples

**Example 1**

> “Every tool call from our agent should be traceable in order.”

Emit structured records with monotonic `step_index` and parent pointers for nested calls.

**Example 2**

> “Compliance wants immutable AI logs for credit decisions.”

Include `policy_version`, `model_id`, `feature_vector_hash`, but **not** raw applicant rows.

**Example 3**

> “Build a Grafana dashboard.”

ETL Mirror REST → columnar store keyed by `consensus_timestamp`.

## Troubleshooting

| Issue | Mitigation |
| --- | --- |
| Message too large | Chunk + manifest hash |
| PII leak | Redact in callback before submit |

## References

- Local: [references/decision-log-schema.md](references/decision-log-schema.md), [references/pipeline-architecture.md](references/pipeline-architecture.md), [references/gdpr-considerations.md](references/gdpr-considerations.md)
- Hedera AI resources: [AI Studio on Hedera](https://docs.hedera.com/hedera/open-source-solutions/ai-studio-on-hedera.md)