hesoDocs
SDK reference /Overview

Overview

HESO ships one Rust core compiled to several surfaces. Pick the one for your runtime, then follow its reference page.

Gating, signing, and verification all run from the same compiled core, so a verdict is the same in Python, in Node, and in a browser. You do not re-implement canonicalization, BLAKE3, or Ed25519 anywhere. You install the package for your runtime and call it.

Which SDK?

Start from the job you have, not the package name.

Your jobPackage
Build a Python agentheso (pip install heso)
Build a Node / TypeScript agent@hesohq/sdk (+ native @hesohq/node)
Verify receipts in a browser or CI@hesohq/verify-wasm
Verify evidence bundles on the CLIheso-verify-cli
Gating is local, verifying is portable

Gating and signing run where your agent runs (Python or Node). Verifying a receipt runs anywhere, including a browser or CI step with no HESO infrastructure and no API key.

A worked path: a Python agent

Building a Python agent? Here is the order you do things, with the page for each step. The Node path mirrors it with @hesohq/sdk.

  1. Install the SDK. pip install heso — see installation.
  2. Run heso.init(). One call at startup loads your policy and signing key. See the Python quickstart.
  3. Decorate your tools. Wrap each tool with @heso.tool so every call is captured, gated, and signed. See the Python quickstart.
  4. Write a policy. Define [[rule]] blocks in heso.toml that say which actions allow, block, redact, or need approval. See writing policy.
  5. Run your agent. Each action now produces a signed receipt. Verify it offline with any surface above.

Framework adapters

If you use a framework, you usually do not call gating by hand. HESO ships adapters for the Vercel AI SDK and Mastra that gate tools for you. See framework adapters.

Per-language reference

Each surface has a full reference page covering its function list.

SurfacePackageReference
PythonhesoSDK reference — Python
TypeScript / Node@hesohq/sdkSDK reference — TypeScript
Node native addon@hesohq/nodeSDK reference — Node
Browser (WASM)@hesohq/verify-wasmSDK reference — Browser
CLIheso / heso-verify-cliSDK reference — CLI

Versioning

Every package releases in lockstep on one version number, and they bundle the same Rust core. The wire format is the stable contract: the algorithm is heso-action/v2+ed25519. A receipt signed today verifies on any surface that recognizes it. The packages are pre-1.0, so pin your versions and handle every verification outcome instead of assuming success.

Next steps

hesoPython SDKinit, the @tool / @destructive decorators, wrap, and suspend / resume.@hesohq/sdkTypeScript SDKgate, assertGate, wrap, the cloud client, and the wire types.Framework adaptersGate tools through the Vercel AI SDK and Mastra without wiring gating by hand.