Skip to main content
In this guide, you’ll go from zero to a running AI agent on Kubernetes in under five minutes. You’ll use the @hexr_agent decorator to register your agent, hexr_llm to make a traced OpenAI call, and hexr_tool to access AWS S3 — all without a single credential in your code. By the end, your agent will have a SPIFFE cryptographic identity, automatic cost attribution, and LLM observability out of the box.

​
Prerequisites

  • Python 3.10 or later
  • Docker (for local builds) or a Hexr Cloud account
  • kubectl configured with a Kubernetes cluster

​
Steps

1

Install the SDK

Install the Hexr SDK with the CLI extras:
uv pip install "hexr-sdk[cli]" --extra-index-url https://pypi.hexr.cloud/simple/
2

Write your agent

Create my_agent.py:
my_agent.py
import openai
from hexr import hexr_agent, hexr_tool, hexr_llm
from hexr.vault import VaultClient

@hexr_agent(name="my-first-agent", tenant="my-team")
def main():
    # Fetch API key from Hexr Vault (no secrets in code)
    vault = VaultClient()
    api_key = vault.get("api-keys/openai")

    # Wrap the OpenAI client — automatic OTel tracing on every call
    client = hexr_llm(openai.OpenAI(api_key=api_key))

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "What is the capital of France?"}],
    )
    print(response.choices[0].message.content)

    # Get an authenticated S3 client via SPIFFE identity (no AWS keys)
    s3 = hexr_tool("aws_s3")
    buckets = s3.list_buckets()
    print(f"Found {len(buckets['Buckets'])} buckets")

if __name__ == "__main__":
    main()
The VaultClient reads secrets scoped to your agent’s SPIFFE identity — no other agent can access them, even on the same cluster.
3

Build

Run hexr build to analyze your agent and generate deployment artifacts:
hexr build my_agent.py --tenant my-team
Expected output
Analyzing my_agent.py...
  Framework: pure_python
  Agents: 1 (my-first-agent)
  Resources: aws_s3
  A2A: disabled

Generated .hexr/ (5 files)
hexr build performs static AST analysis — it discovers your agent name, framework, cloud resources, and A2A configuration without executing your code.
4

Push

Build and push the container image to your registry:
hexr push
Expected output
Building for: linux/amd64, linux/arm64
Pushing to: registry/my-team/my-first-agent:latest

✓ Image pushed
✓ Vulnerability scan: 0 critical
5

Deploy

Apply the generated manifests to your cluster:
hexr deploy
Expected output
Applying manifests to tenant-my-team...
  ✓ Namespace created
  ✓ RBAC applied
  ✓ Agent pod created (4/4 containers)

Agent deployed!
  SPIFFE ID: spiffe://demo.hexr.dev/agent/my-team/my-first-agent/main

​
What just happened?

1

AST analysis

hexr build analyzed your Python code and discovered the agent name, framework, cloud resources, and A2A configuration — all without running your code.
2

Identity assignment

Your agent received a SPIFFE identity: spiffe://demo.hexr.dev/agent/my-team/my-first-agent/main. This identity is used for all authentication.
3

Credential injection

When your agent calls hexr_tool("aws_s3"), the platform automatically exchanges the SPIFFE identity for short-lived AWS credentials. No AWS keys in your code.
4

Observability

Every hexr_llm() and hexr_tool() call is automatically traced with OpenTelemetry. Check the dashboard for traces, metrics, and costs.

​
Next steps

Multi-framework agents

Use CrewAI, LangChain, or AutoGen with Hexr — each role gets its own SPIFFE identity.

Agent-to-agent communication

Enable agents to discover, delegate to, and collaborate with each other over mTLS.

Secure secrets

Store and retrieve API keys with per-agent, per-process isolation.

SDK reference

Full API documentation for @hexr_agent, hexr_tool, hexr_llm, and more.