Skip to main content
The Hexr Python SDK is the entry point for building identity-first AI agents. With a single decorator, your agent receives a cryptographic SPIFFE identity that gates every downstream operation — cloud credential exchange, secret access, LLM cost tracking, and inter-agent communication — so you write agent logic instead of infrastructure plumbing.

​
Installation

uv pip install "hexr-sdk[cli]" --extra-index-url https://pypi.hexr.cloud/simple/
The Hexr SDK is distributed via a private PyPI registry. You need access credentials. For Hexr Cloud users, hexr login configures this automatically.

​
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")
    
    # Code execution in Firecracker microVM
    import hexr.sandbox
    result = hexr.sandbox.exec("import pandas; print(pandas.__version__)")
    
    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 when you run this agent:
  • A SPIFFE identity is assigned to this process
  • All cloud calls are authenticated via a 3-tier credential cache
  • Every LLM call is traced with model, tokens, latency, and cost
  • OpenTelemetry spans are emitted for every SDK operation
  • An A2A agent card is served for inter-agent discovery

​
Module map

ImportPurposeDocs
from hexr import hexr_agentAgent decoratorReference
from hexr import hexr_toolCloud tool factoryReference
from hexr import hexr_llmLLM observability proxyReference
import hexr.vaultSecrets managementReference
import hexr.gatewayMCP tool gatewayReference
import hexr.sandboxCode executionReference
import hexr.browserBrowser automationReference
import hexr.guardLLM Guard scanningReference
from hexr.a2a import A2AClientAgent-to-agent communicationReference

​
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.sandbox  # Module loads only now
This keeps agent startup fast and avoids loading unnecessary dependencies.

​
Environment variables

Most environment variables are set automatically by hexr deploy. For self-hosted deployments, you can override the defaults to point at your own cluster services:
VariableDescription
HEXR_FRAMEWORKFramework type — auto-detected by hexr build, set at deploy time
HEXR_TENANTTenant identifier — defaults to the tenant param on @hexr_agent
HEXR_AGENT_NAMEAgent name — defaults to the name param on @hexr_agent
HEXR_SANDBOX_ENABLEDSet to true to enable sandbox features (auto-detected in most deployments)
HEXR_LLM_GUARD_ENABLEDSet to true to enable LLM Guard scanning (auto-detected in most deployments)
On Hexr Cloud, all service endpoints are configured automatically. On self-hosted deployments, endpoint URLs for Vault, Gateway, Sandbox, and the OTel Collector are injected by the Hexr Helm chart at deploy time — you don’t set these manually.

​
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
    pass
except CredentialError:
    # Cloud credential exchange failed
    pass
except HexrError:
    # Any other SDK error
    pass
ExceptionWhen raised
HexrErrorBase exception for all SDK errors
AuthenticationErrorSPIFFE auth fails (no SVID available)
CredentialErrorCloud credential exchange fails
ConfigurationErrorInvalid SDK configuration
BuildErrorhexr build processing fails
DeploymentErrorhexr deploy fails
FrameworkErrorAgent framework detection fails
ProcessContextErrorProcess context file creation fails
GuardrailErrorLLM Guard blocks the request (has .scanners dict)