HDP

HDP — Human Delegation Provenance Protocol

A cryptographic chain-of-custody protocol for agentic AI systems. Every action an AI agent takes, traceable back to the human who authorized it.

[](https://www.npmjs.com/package/@helixar_ai/hdp) [](https://pypi.org/project/hdp-crewai/) [](https://pypi.org/project/hdp-grok/) [](https://www.apache.org/licenses/LICENSE-2.0) [](https://www.typescriptlang.org/) [](https://www.python.org/) [](https://nodejs.org/) [](https://github.com/Helixar-AI/HDP/actions) [](https://github.com/Helixar-AI/HDP/blob/main/tests/security/offline-verification.test.ts) [](https://datatracker.ietf.org/doc/html/rfc8032) [](./packages/hdp-mcp) [](./packages/hdp-crewai) [](./packages/hdp-grok) [](./packages/hdp-autogen) [](./packages/hdp-agent-framework) [](./packages/hdp-langchain) [](./packages/llama-index-callbacks-hdp) [](https://pypi.org/project/llama-index-callbacks-hdp/) [](https://github.com/Helixar-AI/ReleaseGuard) [](https://doi.org/10.5281/zenodo.19332023) [](https://arxiv.org/abs/2604.04522)

---

What is HDP?

HDP (Human Delegation Provenance) is an open protocol that captures, structures, cryptographically signs, and verifies the human authorization context in agentic AI systems.

When a person authorizes an AI agent to act — and that agent delegates to another agent, and another — HDP creates a tamper-evident chain of custody from the authorizing human to every downstream action. The full delegation trail is encoded in a compact, self-contained token signed with Ed25519 and canonicalized with RFC 8785. Verification is fully offline: it requires only a public key, no central registry, no network call.

Who it is for: developers building AI agents with Grok/xAI, CrewAI, MCP servers, or any OpenAI-compatible API who need accountability, auditability, and proof of human authorization at every step.

---

Packages

| Package | Registry | Language | Framework | Description | | ------------------------------------------------------ | ------------------------------------------------------------ | ---------- | --------------------- | -------------------------------------------------------------------------- | | [@helixar_ai/hdp](./src) | npm | TypeScript | Any | Core SDK — issue, extend, verify HDP tokens | | [@helixar_ai/hdp-mcp](./packages/hdp-mcp) | npm | TypeScript | MCP | MCP middleware — attaches HDP to any MCP server | | [@helixar_ai/hdp-physical](./packages/hdp-physical) | npm | TypeScript | Physical AI / Robotics | HDP-P guardrails — signs EDTs and blocks unsafe robot actions pre-execution | | [hdp-physical](./packages/hdp-physical-py) | PyPI | Python | Physical AI / Robotics | HDP-P guardrails — Python SDK for EDT issuance and pre-execution checks | | [hdp-crewai](./packages/hdp-crewai) | PyPI | Python | CrewAI | CrewAI middleware — attaches HDP to any crew | | [hdp-grok](./packages/hdp-grok) | PyPI | Python | Grok / xAI | Grok middleware — attaches HDP to any xAI conversation | | [hdp-autogen](./packages/hdp-autogen) | PyPI | Python | AutoGen | AutoGen middleware — attaches HDP to any AutoGen agent or GroupChat | | [hdp-agent-framework](./packages/hdp-agent-framework) | PyPI | Python | Microsoft agent-framework | agent-framework middleware — attaches HDP to any Agent or workflow | | [@helixar_ai/hdp-autogen](./packages/hdp-autogen-ts) | npm | TypeScript | AutoGen | AutoGen middleware — HdpAgentWrapper + hdpMiddleware for AutoGen flows | | [hdp-langchain](./packages/hdp-langchain) | PyPI | Python | LangChain / LangGraph | LangChain middleware — attaches HDP to any chain, agent, or LangGraph node | | [llama-index-callbacks-hdp](./packages/llama-index-callbacks-hdp) | PyPI | Python | LlamaIndex | LlamaIndex integration — callback handler, instrumentation dispatcher, node postprocessor | | [hdp-llamaindex](./packages/hdp-llamaindex) | PyPI | Python | LlamaIndex | Metapackage — pip install hdp-llamaindex for HDP-first users |

Install

TypeScript / Node.js

npm install @helixar_ai/hdp

TypeScript / Physical AI

npm install @helixar_ai/hdp-physical

Python / CrewAI

pip install hdp-crewai

Python / Physical AI

pip install hdp-physical

Python / Grok (xAI API)

pip install hdp-grok

Python / AutoGen

pip install hdp-autogen

Python / Microsoft agent-framework

pip install hdp-agent-framework

Python / LangChain

pip install hdp-langchain

Python / LlamaIndex

pip install llama-index-callbacks-hdp
# or, from the HDP side:
pip install hdp-llamaindex

---

Quickstart — TypeScript

Issue a root token, extend it through a delegation chain, verify it offline. Under 2 minutes.

import {
  generateKeyPair,
  issueToken,
  extendChain,
  verifyToken,
} from "@helixar_ai/hdp";

// 1. Generate a key pair for the issuer
const { privateKey, publicKey } = await generateKeyPair();

// 2. Issue a token (the human authorization event)
let token = await issueToken({
  sessionId: "sess-20260326-abc123",
  principal: {
    id: "usr_alice_opaque",
    id_type: "opaque",
    display_name: "Alice Chen",
  },
  scope: {
    intent: "Analyze Q1 sales data and generate a summary report.",
    authorized_tools: ["database_read", "file_write"],
    authorized_resources: ["db://sales/q1-2026"],
    data_classification: "confidential",
    network_egress: false,
    persistence: true,
    max_hops: 3,
  },
  signingKey: privateKey,
  keyId: "alice-signing-key-v1",
});

// 3. Extend the chain as the task delegates to agents
token = await extendChain(
  token,
  {
    agent_id: "orchestrator-v2",
    agent_type: "orchestrator",
    action_summary: "Decompose analysis task and delegate to sub-agents.",
    parent_hop: 0,
  },
  privateKey,
);

token = await extendChain(
  token,
  {
    agent_id: "sql-agent-v1",
    agent_type: "sub-agent",
    action_summary: "Execute read query against sales database.",
    parent_hop: 1,
  },
  privateKey,
);

// 4. Verify at any point in the chain — fully offline, no network call
const result = await verifyToken(token, {
  publicKey,
  currentSessionId: "sess-20260326-abc123",
});

console.log(result.valid); // true
console.log(token.chain.length); // 2

---

Physical AI Integration

@helixar_ai/hdp-physical and hdp-physical extend HDP into robotics with Embodied Delegation Tokens (EDTs) and a pre-execution guard. Before a motion command reaches an actuator, HDP-P verifies the EDT signature, checks the irreversibility ceiling, enforces excluded zones, and blocks actions that exceed force or velocity limits.

import {
  EdtBuilder,
  IrreversibilityClass,
  PreExecutionGuard,
  signEdt,
} from "@helixar_ai/hdp-physical";
import { generateKeyPair } from "@helixar_ai/hdp";

const { privateKey, publicKey } = await generateKeyPair();

const edt = new EdtBuilder()
  .setEmbodiment({
    agent_type: "robot_arm",
    platform_id: "aloha_v2",
    workspace_scope: "zone_A",
  })
  .setActionScope({
    permitted_actions: ["pick", "place", "move"],
    excluded_zones: ["human_zone"],
    max_force_n: 45,
    max_velocity_ms: 0.5,
  })
  .setIrreversibility({
    max_class: IrreversibilityClass.REVERSIBLE_WITH_EFFORT,
    class2_requires_confirmation: true,
    class3_prohibited: true,
  })
  .setPolicyAttestation({
    policy_hash: "sha256-of-weights",
    training_run_id: "run-1",
    sim_validated: true,
  })
  .setDelegationScope({
    allow_fleet_delegation: false,
    max_delegation_depth: 1,
    sub_agent_whitelist: [],
  })
  .build();

const signedEdt = await signEdt(edt, privateKey, "robot-key-v1");
const guard = new PreExecutionGuard();

const decision = await guard.authorize(
  {
    description: "pick box from left bin",
    force_n: 5,
    velocity_ms: 0.2,
  },
  signedEdt,
  publicKey,
);

console.log(decision.approved);

For Python, install hdp-physical and use the same EDT model and guard flow, with optional lerobot and gemma extras for adapters and interception.

→ [Full TypeScript physical AI docs](./packages/hdp-physical/README.md) → [Full Python physical AI docs](./packages/hdp-physical-py/README.md)

---

Grok / xAI Integration

hdp-grok attaches HDP to any Grok conversation via three native tool schemas. No changes to your prompts or model configuration are required — Grok calls hdp_issue_token, hdp_extend_chain, and hdp_verify_token as regular tool calls, and HdpMiddleware handles everything statelessly behind the scenes.

import json
import os
from openai import OpenAI
from hdp_grok import HdpMiddleware, get_hdp_tools

# xAI API — OpenAI-compatible endpoint
client = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

# One middleware instance per conversation
middleware = HdpMiddleware(
    signing_key=os.getenv("HDP_SIGNING_KEY"),  # base64url Ed25519 private key
    principal_id="user@example.com",
)

messages = [{"role": "user", "content": "Issue an HDP token and delegate to research-agent."}]

while True:
    response = client.chat.completions.create(
        model="grok-3",
        messages=messages,
        tools=get_hdp_tools(),  # inject the three HDP tool schemas
    )
    choice = response.choices[0]

    if choice.finish_reason == "tool_calls":
        messages.append(choice.message)
        for tc in choice.message.tool_calls:
            result = middleware.handle_tool_call(
                name=tc.function.name,
                args=json.loads(tc.function.arguments),
            )
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": json.dumps(result),
            })
    else:
        print(choice.message.content)
        break

# Full delegation chain — verifiable offline with the public key
print(middleware)  # HdpMiddleware(session_id='...', hops=2, valid=True)

Three HDP tools Grok can call

| Tool | Required args | What it does | | ------------------ | -------------- | --------------------------------------------------------- | | hdp_issue_token | — | Signs a root token for the session and principal | | hdp_extend_chain | delegatee_id | Appends a signed delegation hop (e.g. to a sub-agent) | | hdp_verify_token | token | Verifies the full chain using the middleware's public key |

What HdpMiddleware manages for you

• Holds the Ed25519 signing key (bytes, hex, base64url, or HDP_SIGNING_KEY env var)
• Maintains the current token and hop counter for the conversation lifetime
• Routes all hdp_* tool calls via handle_tool_call(name, args)
• Handles both snake_case and camelCase argument names from Grok
• Raises typed errors: HdpTokenMissingError, HdpTokenExpiredError, HdpSigningKeyError

→ [Full Grok integration docs](./packages/hdp-grok/README.md)

---

CrewAI Integration

hdp-crewai attaches HDP to any CrewAI crew with a single middleware.configure(crew) call. No changes to your agents, tasks, or crew configuration are required.

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from crewai import Agent, Crew, Task
from hdp_crewai import HdpMiddleware, HdpPrincipal, ScopePolicy, verify_chain

private_key = Ed25519PrivateKey.generate()

middleware = HdpMiddleware(
    signing_key=private_key.private_bytes_raw(),
    session_id="q1-review-2026",
    principal=HdpPrincipal(id="analyst@company.com", id_type="email"),
    scope=ScopePolicy(
        intent="Analyse Q1 sales data and produce a summary",
        authorized_tools=["FileReadTool", "CSVAnalysisTool"],
        max_hops=5,
    ),
)

crew = Crew(agents=[...], tasks=[...])
middleware.configure(crew)  # attach HDP — one line, zero crew changes
crew.kickoff()

# Verify the full delegation chain offline
result = verify_chain(middleware.export_token(), private_key.public_key())
print(result.valid, result.hop_count, result.violations)

| # | Consideration | Behaviour | | --- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Scope enforcement | step_callback checks every tool call against authorized_tools. strict=True raises HDPScopeViolationError; default logs and records in the audit trail. | | 2 | Delegation depth | max_hops is enforced per run; hops beyond the limit are skipped and warned. | | 3 | Token size / perf | Ed25519 = 64 bytes/hop. All operations are non-blocking — failures log, never halt the crew. | | 4 | Verification | verify_chain(token, public_key) validates root + every hop offline. | | 5 | Memory integration | Signed token is persisted to CrewAI's storage directory for retroactive auditing. |

→ [Full CrewAI integration docs](./packages/hdp-crewai/README.md)

---

AutoGen Integration

hdp-autogen attaches HDP to any AutoGen ConversableAgent or GroupChatManager with a single middleware.configure(target) call. Each speaker turn in a GroupChat is recorded as a delegation hop.

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from autogen import ConversableAgent, GroupChat, GroupChatManager
from hdp_autogen import HdpMiddleware, HdpPrincipal, ScopePolicy, verify_chain

private_key = Ed25519PrivateKey.generate()

middleware = HdpMiddleware(
    signing_key=private_key.private_bytes_raw(),
    session_id="research-2026-q1",
    principal=HdpPrincipal(id="researcher@lab.edu", id_type="email"),
    scope=ScopePolicy(
        intent="Coordinate research agents to summarise recent papers",
        authorized_tools=["web_search", "file_reader"],
        max_hops=10,
    ),
)

researcher = ConversableAgent("researcher", ...)
reviewer = ConversableAgent("reviewer", ...)
groupchat = GroupChat(agents=[researcher, reviewer], messages=[])
manager = GroupChatManager(groupchat=groupchat, ...)

middleware.configure(manager)  # hooks all agents + wraps run_chat
manager.run_chat(messages=[{"role": "user", "content": "Su

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Helixar-AI](https://github.com/Helixar-AI)
- **Source:** [Helixar-AI/HDP](https://github.com/Helixar-AI/HDP)
- **License:** Apache-2.0
- **Homepage:** https://helixar.ai/about/labs/hdp/

Install and usage instructions live in the source repository linked above.