Enterprise Action Receipt Agent

Enterprise Action Receipt Agent is a small Hedera Agent Kit submission for the Hedera AI Agent Bounty. It gives an enterprise agent a plugin-style tool for recording approved real-world workflow actions as tamper-evident Hedera Consensus Service receipts, and exposes the same tool through a Model Context Protocol server for MCP-capable agent clients.

The project is intentionally narrow: it does not execute payments, touch customer systems, or move funds. It records the approval evidence around an action that already passed a human or system approval step.

What It Does

• Validates an approved enterprise action payload.
• Enforces an approval policy before any receipt can be published.
• Builds a canonical JSON receipt and SHA-256 payload hash.
• Publishes the receipt to Hedera Consensus Service when HEDERA_ACCOUNT_ID and HEDERA_PRIVATE_KEY are configured.
• Runs the same flow in dry-run mode without credentials for local review, tests, and demos.

Why Hedera

The Hedera Agent Kit provides agent-facing Hedera primitives, including Consensus Service tools and execution modes. This project uses that pattern for an enterprise plugin: the agent can create a durable action trail without being able to spend money or perform the underlying workflow action.

Quick Start

npm install
npm test
npm run build
npm run demo
npm run mcp:smoke

Expected dry-run output:

{
  "agent_mode": "dry-run",
  "hedera_agent_kit_configured": false,
  "tool": "record_enterprise_action_receipt",
  "publish_mode": "dry-run",
  "topic_id": null,
  "transaction_id": null,
  "receipt_hash": "..."
}

MCP Mode

Week 3 adds a local MCP server around the existing Hedera receipt tool:

npm run --silent mcp

The server exposes one tool, record_enterprise_action_receipt, over stdio. Use --silent so npm does not print a banner to stdout before the MCP JSON-RPC stream. The tool accepts the same approved-action payload as the CLI demo, applies the same policy checks, and returns structured MCP content with the receipt hash, schema version, Hedera mode, topic ID, and transaction ID when HCS publishing is configured.

For a quick non-interactive check:

npm run mcp:smoke

The smoke command invokes the MCP-shaped adapter in dry-run mode and prints the structured output that an MCP client receives from the tool.

Hedera Testnet Mode

Create .env from .env.example, then provide a Hedera testnet account and private key:

cp .env.example .env
npm run demo

If HEDERA_TOPIC_ID is omitted, the publisher creates a new HCS topic named Enterprise action receipts.

Tool Contract

The agent tool is named record_enterprise_action_receipt.

Required fields:

• tenantId
• workflow
• actionType
• actionId
• summary
• actor
• approvedBy
• approvalTicket

Optional fields:

• externalRefs
• metadata

Safety Controls

• approvedBy and approvalTicket are mandatory.
• The policy rejects money-movement wording such as transfer, withdraw, or drain wallet.
• The tool publishes receipts only. It does not execute the business action being described.
• Mainnet use should keep the human approval system outside the agent and pass only minimal receipt metadata.

Bounty Notes

This project targets:

• Week 2 Enterprise Agent + Plugin: integrate Hedera Agent Kit with a real-world enterprise approval/audit workflow.
• Week 3 MCP or x402 Agent: expose the approved-action receipt workflow as an MCP tool for agent clients while keeping HCS publishing as the Hedera-backed execution path.