Your first ten minutes

Install the SDK, mark up an agent, and have Hexr recognise it. About ten minutes, and it needs no cluster, no cloud account and no Docker.

Every command on this page was run end to end on macOS and in a clean Linux container before it was written. Where something does not work yet, the page says so.

What this page does not cover

Deploying that agent and watching it receive a cryptographic identity needs a Kubernetes cluster running the Hexr runtime. That is a separate guide. This page stops at the point where Hexr understands your code.

1. Install

pip install 'hexr-sdk[cli]'

Python 3.11 to 3.13, on macOS, Linux x86_64 or Linux aarch64. Nothing else. A clean install takes about a second.

python -c "import hexr; print(hexr.__version__)"
# 0.5.31

2. Mark up an agent

An ordinary LangGraph app with two decorators added. Save as agent.py:

agent.py

from langgraph.graph import StateGraph, END
from hexr import hexr_agent, hexr_tool

@hexr_tool("aws_s3")
def fetch_claim(claim_id: str) -> str:
    return f"claim {claim_id}"

def plan(state): return state
def act(state):  return state

@hexr_agent(name="triage", tenant="acme")
def main():
    g = StateGraph(dict)
    g.add_node("plan", plan)
    g.add_node("act", act)
    g.add_edge("plan", "act")
    g.add_edge("act", END)
    g.set_entry_point("plan")
    return g.compile().invoke({})

Two things worth noticing. @hexr_agent takes no framework argument. It does not need to know what you are building on. The framework is recognised separately, from your source. @hexr_tool("aws_s3") names the resource, not a credential. Once deployed, the agent process never holds a long-lived secret. It proves which process it is and is handed a credential that expires in minutes.

3. Let Hexr recognise it

hexr analyze .

Framework: LangGraph (id=langgraph, confidence=1.00)
                          Agents (4)
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Name ┃ Class                                   ┃ Framework ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━┩
│      │ langgraph.graph.StateGraph              │ langgraph │
│      │ langgraph.graph.StateGraph#orchestrator │ langgraph │
└──────┴─────────────────────────────────────────┴───────────┘

LangGraph was not installed when that ran. Recognition is static: it reads your source, it does not import or execute your code. Add --json for a machine-readable manifest, which is what hexr build consumes later.

Recognition is data, not code

Fifteen frameworks are recognised today: adk · agno · autogen · claude-agent · crewai · dspy · langchain · langgraph · llamaindex · mcp · openai-agents · pydantic-ai · smolagents · strands · bespoke (in-house) Measured confidence on real code: LangGraph 1.00, CrewAI 1.00, Pydantic AI 0.90. And seven agentic patterns: prompt chaining, routing, parallelisation, orchestrator-workers, evaluator-optimiser, ReAct, reflection. Each is a YAML signature pack rather than product code, and the packs are public at github.com/hexrdev/hexr-signatures. A framework nobody has heard of yet is a file, not a release. If you maintain a framework, you can open a pull request instead of waiting for us to notice you.

4. Build a container and manifests

Still no cluster needed. hexr build turns the file into a Dockerfile, an agent pod spec, and the supporting Kubernetes manifests:

hexr build agent.py --tenant acme --target development

✅ Build completed successfully!
📦 Image: acme/agent:development
📂 Artifacts: .hexr

.hexr/manifests/ now holds agent-pod.yaml, the Envoy sidecar config, namespace, RBAC, network policy and resource quota. The SDK wheel matching your installed version is baked in alongside them. Applying those to a cluster running the Hexr runtime is where the identity appears, and that is the next guide. See hexr build for every option and a verified first-run transcript.

What happens once it is deployed

So the payoff is clear, briefly:

Every agent process gets its own SPIFFE identity, valid four hours, held in memory and never written to disk or an environment variable.
A process that is not registered is refused in about fifteen seconds, and the refusal is itself a signed record.
Every tool call, model call and agent-to-agent call becomes a hash-chained, signed evidence row.
Your auditor is handed one zip whose verify.html re-derives every hash and signature on their own laptop, offline, with nothing installed.

Troubleshooting

Symptom	Cause	Fix
`could not compile hexr_analyzer` on macOS	SDK ≤ 0.5.30 shipped no macOS wheel	`pip install -U hexr-sdk`
`Building wheel for psutil ... error` on ARM Linux	SDK ≤ 0.5.30 pinned `psutil<6`, which has no aarch64 wheel	`pip install -U hexr-sdk`
`hexr: the CLI needs the optional cli extra`	You installed the base package	`pip install 'hexr-sdk[cli]'`
Agent names are blank in the table	Expected. That column lists framework-detected classes; `@hexr_agent(name=...)` names are in the JSON	`hexr analyze . --json`

Per-process identity

Why the identity is per process rather than per pod.

Evidence verification

What your auditor actually receives, and how they check it.

SDK Overview

Decorators & Functions

Modules

Your first ten minutes

What this page does not cover

1. Install

2. Mark up an agent

3. Let Hexr recognise it

Recognition is data, not code

4. Build a container and manifests

What happens once it is deployed

Troubleshooting

Next

Per-process identity

Evidence verification

​What this page does not cover

​1. Install

​2. Mark up an agent

​3. Let Hexr recognise it

​Recognition is data, not code

​4. Build a container and manifests

​What happens once it is deployed

​Troubleshooting

​Next

Per-process identity

Evidence verification

What this page does not cover

1. Install

2. Mark up an agent

3. Let Hexr recognise it

Recognition is data, not code

4. Build a container and manifests

What happens once it is deployed

Troubleshooting

Next