open-ahp 1.0.0

Agent History Protocol — tamper-evident recording for AI agents

AHP -- Agent History Protocol

The Agent History Protocol (AHP) is an open standard for tamper-evident recording of AI agent actions. Every tool call, inference, and delegation is written to a hash-chained log that anyone can verify — a flight recorder for AI agents.

Demo

Install → Run 3 real AI agents with Gemini Flash → Inspect chain records (HTTP, MCP, A2A protocols) → Verify integrity & compliance

Documents

1. This README — quickstart and CLI reference
2. Specification — normative protocol spec for implementers

Install

Python

Requires Python 3.9+.

pip install open-ahp                # core SDK
pip install open-ahp[signing]       # + Ed25519 signing (Level 2+)
pip install open-ahp[all]           # + signing, YAML config, PCRE2 filters, gRPC

TypeScript / Node.js

Requires Node.js 18+.

npm install open-ahp

See the TypeScript SDK README for full API docs.

Quickstart

Python

from ahp.recorder import AHPRecorder
from ahp.core.types import Protocol, ActionType

recorder = AHPRecorder(agent_name="my-agent")
recorder.record_action(
    tool_name="read_file",
    parameters=b'{"path": "/etc/motd"}',
    result=b'"Welcome!"',
    protocol=Protocol.MCP,
    action_type=ActionType.TOOL_CALL,
)
recorder.close()

TypeScript

import { AHPRecorder, Protocol, ActionType } from "open-ahp";

const recorder = new AHPRecorder({ agentName: "my-agent" });
recorder.recordAction({
    toolName: "read_file",
    parameters: Buffer.from('{"path": "/etc/motd"}'),
    result: Buffer.from('"Welcome!"'),
    protocol: Protocol.MCP,
    actionType: ActionType.TOOL_CALL,
});
recorder.close();

Record an LLM inference

recorder.record_inference(
    tool_name="claude-sonnet-4",
    model_id="claude-sonnet-4-6",
    input_token_count=1200,
    output_token_count=340,
    reasoning_tokens=512,        # thinking/reasoning tokens (o3, Gemini, DeepSeek-R1)
    cache_read_tokens=800,       # prompt tokens served from cache
    provider="anthropic",        # auto-detected if using interceptors
    # cost_nano_usd auto-estimated from configurable pricing table
)

Auto-instrumentation

Automatically capture all HTTP calls — provider, model, tokens, cost, and reasoning tokens are extracted automatically:

# Python — patches requests, httpx, urllib
from ahp.interceptors.http_auto import install_http_interceptor
install_http_interceptor(recorder)

# Supports: OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock,
#           Groq, Together AI, Fireworks, DeepSeek, Mistral, Cohere, Perplexity
# Add custom providers via ahp.yaml (see Configuration below)

// TypeScript
import { installHttpInterceptor } from "open-ahp";
installHttpInterceptor(recorder);  // patches globalThis.fetch

Inspect the log

$ ahp log --chain my-agent.ahp

   # | Time     | Type       | Tool/Name                 | Status  | Auth                 |  Latency
-----------------------------------------------------------------------------------------------
   1 | 14:32:01 | BOOT       | --                        | --      | --                   |       --
   2 | 14:32:01 | TOOL_CALL  | read_file                 | SUCCESS | AUTH_NONE            |     42ms

CLI Commands

ahp log    [--chain FILE] [--last N]         Show records
ahp show   <seq> [--chain FILE] [--tree]     Show record details
ahp verify [--chain FILE]                    Verify chain integrity
ahp export [--chain FILE]                    Export as JSON
ahp trace  <session_prefix> [--chain FILE]   Trace session decisions
ahp gaps   [--chain FILE]                    List gap records
ahp init   [<agent_name>]                    Setup wizard
ahp keygen                                   Generate Ed25519 keypair

Export

Export to JSONL, CSV, or OTLP (OpenTelemetry):

from ahp.export import export_jsonl, export_csv, OTLPExporter

export_jsonl("my-agent.ahp", "audit.jsonl")
export_csv("my-agent.ahp", "audit.csv")

exporter = OTLPExporter(endpoint="http://localhost:4318/v1/logs")
exporter.export_chain("my-agent.ahp")

Verify

$ ahp verify --chain my-agent.ahp

Verifying chain: my-agent
Records: 42

Checking hash chain...  ██████████████████████████████ 42/42

CHAIN VALID
   Hash chain:    42 records verified, 0 broken links
   Gaps:          0

Configuration

Create ahp.yaml for custom pricing and provider patterns:

defaults:
  level: 2

# Override or add model pricing (nano USD per token)
pricing:
  gpt-4o: [2500, 10000]           # $2.50 / $10 per 1M tokens
  my-fine-tuned-model: [500, 2000] # custom model

# Add custom LLM endpoint detection
providers:
  - pattern: 'llm\.mycompany\.internal'
    name: internal.llm.chat
    provider: internal

Built-in pricing covers OpenAI, Anthropic, Google Gemini, Mistral, and DeepSeek. User entries merge on top.

Specification

Full protocol specification: agent-history-protocol-spec.md

License

Apache 2.0 — see LICENSE.