> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> The Hexr Python SDK gives your agents cryptographic identity, authenticated cloud tools, LLM observability, and inter-agent communication — with minimal code changes.

## Installation

<CodeGroup>
  ```bash uv (recommended) theme={null}
  uv pip install "hexr-sdk[cli]" --extra-index-url https://pypi.hexr.cloud/simple/
  ```

  ```bash pip theme={null}
  pip install "hexr-sdk[cli]" --extra-index-url https://pypi.hexr.cloud/simple/
  ```
</CodeGroup>

<Warning>
  The Hexr SDK is distributed via private PyPI. You need access credentials.
  For Hexr Cloud users, `hexr login` configures this automatically.
</Warning>

***

## Quick Example

```python theme={null}
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:**

* 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 →](/sdk/hexr-agent) |
| `from hexr import hexr_tool`     | Cloud tool factory           | [Reference →](/sdk/hexr-tool)  |
| `from hexr import hexr_llm`      | LLM observability proxy      | [Reference →](/sdk/hexr-llm)   |
| `import hexr.vault`              | Secrets management           | [Reference →](/sdk/vault)      |
| `import hexr.gateway`            | MCP tool gateway             | [Reference →](/sdk/gateway)    |
| `import hexr.sandbox`            | Code execution               | [Reference →](/sdk/sandbox)    |
| `import hexr.browser`            | Browser automation           | [Reference →](/sdk/browser)    |
| `import hexr.guard`              | LLM Guard scanning           | [Reference →](/sdk/guard)      |
| `from hexr.a2a import A2AClient` | Agent-to-agent communication | [Reference →](/sdk/a2a)        |

***

## 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:

```python theme={null}
import hexr.vault    # Module loads only now
import hexr.sandbox  # 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`:

```python theme={null}
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) |