SDK Overview

New here? Start with the ten-minute quickstart

Install, decorate one function, and see a signed evidence row before reading any of this page.

Installation

uv pip install "hexr-sdk[cli]"

pip install "hexr-sdk[cli]"

hexr-sdk is on public PyPI. No credentials, no index URL, no hexr login. The private index at pypi.hexr.cloud exists but is an internal mirror, not a requirement.

Quick Example

from hexr import hexr_agent, hexr_tool, hexr_llm
import openai

@hexr_agent(name="market-analyst", tenant="acme-corp", a2a=True)
def analyze_market(sector: str) -> dict:
    # Authenticated S3 client — zero credential management
    s3 = hexr_tool("aws_s3")
    
    # LLM with automatic cost tracking and tracing
    client = hexr_llm(openai.OpenAI())
    
    # Secrets from SPIFFE-native vault — no API keys
    import hexr.vault
    api_key = hexr.vault.get("research/api-key")
    
    
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": f"Analyze the {sector} market"}]
    )
    
    return {"analysis": response.choices[0].message.content}

What happens automatically:

SPIFFE identity assigned to this process
All cloud calls authenticated via 3-tier credential cache
Every LLM call traced with model, tokens, latency, cost
OpenTelemetry spans emitted for every operation
A2A agent card served for inter-agent discovery

Module Map

Import	Purpose	Docs
`from hexr import hexr_agent`	Agent decorator	Reference →
`from hexr import hexr_tool`	Cloud tool factory	Reference →
`from hexr import hexr_llm`	LLM observability proxy	Reference →
`import hexr.vault`	Secrets management	Reference →
`import hexr.gateway`	MCP tool gateway	Reference →
`import hexr.guard`	LLM Guard scanning	Reference →
`from hexr.a2a import A2AClient`	Agent-to-agent communication	Reference →

How Loading Works

Only the core module (hexr_agent, hexr_tool, hexr_llm) loads at import time. All other modules are lazy-loaded — they only import when first accessed:

import hexr.vault    # Module loads only now
import hexr.vault  # Module loads only now

This keeps agent startup fast and avoids importing unnecessary dependencies.

Environment Variables

The SDK reads these environment variables (most are set automatically by hexr deploy):

Variable	Default	Description
`HEXR_FRAMEWORK`	auto-detected	Framework type (set by `hexr build`)
`HEXR_TENANT`	decorator param	Tenant identifier
`HEXR_AGENT_NAME`	decorator param	Agent name
`HEXR_SPIFFE_SOCKET`	`/run/spire/sockets/agent.sock`	SPIRE Workload API socket
`HEXR_TRUST_DOMAIN`	`hexr.cloud`	SPIFFE trust domain
`HEXR_CREDENTIAL_URL`	`http://hexr-credential-injector.hexr-system:8080`	Credential Injector endpoint
`HEXR_VAULT_URL`	`http://hexr-vault.hexr-system:8091`	Hexr Vault endpoint
`HEXR_GATEWAY_URL`	`http://hexr-gateway.hexr-system:8090`	Hexr Gateway endpoint
`HEXR_SANDBOX_URL`	`http://hexr-sandbox.hexr-system:8092`	Sandbox endpoint
`HEXR_SANDBOX_ENABLED`	auto-detect	Enable sandbox features
`HEXR_LLM_GUARD_URL`	`http://llm-guard.hexr-system:8000`	LLM Guard endpoint
`HEXR_LLM_GUARD_ENABLED`	auto-detect	Enable guard scanning
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://otel-collector.hexr-system:4317`	OTel Collector endpoint

Exceptions

All SDK exceptions inherit from HexrError:

from hexr import HexrError, AuthenticationError, CredentialError

try:
    s3 = hexr_tool("aws_s3")
except AuthenticationError:
    # SPIFFE identity not available
except CredentialError:
    # Cloud credential exchange failed
except HexrError:
    # Any other SDK error

Exception	When
`HexrError`	Base exception for all SDK errors
`AuthenticationError`	SPIFFE auth fails (no SVID available)
`CredentialError`	Cloud credential exchange fails
`ConfigurationError`	Invalid SDK configuration
`BuildError`	`hexr build` processing fails
`DeploymentError`	`hexr deploy` fails
`FrameworkError`	Agent framework detection fails
`ProcessContextError`	Process context file creation fails
`GuardrailError`	LLM Guard blocks the request (has `.scanners` dict)

SDK Overview

Decorators & Functions

Modules

SDK Overview

New here? Start with the ten-minute quickstart

Installation

Quick Example

Module Map

How Loading Works

Environment Variables

Exceptions

New here? Start with the ten-minute quickstart

​Installation

​Quick Example

​Module Map

​How Loading Works

​Environment Variables

​Exceptions

Installation

Quick Example

Module Map

How Loading Works

Environment Variables

Exceptions