@hexr_agent

Signature

@hexr_agent(
    name: str,
    tenant: str,
    resources: list[str] = None,
    subprocess_support: bool = False,
    regions: dict = None,
    a2a: bool = False,
    skills: list[dict] = None,
    description: str = None,
    version: str = None,
)

Parameters

string

required

The agent’s name. Used in SPIFFE ID generation, Kubernetes resource naming, and observability.Must be kebab-case: research-analyst, content-crew, data-pipeline.

string

required

The tenant (organization) this agent belongs to. Maps to a Kubernetes namespace: tenant-{tenant}.

list[str]

default:"None"

Cloud resources this agent needs access to. Used by OPA policies to scope credential exchange.Examples: ["aws_s3", "gcp_bigquery", "azure_storage"]

bool

default:"False"

Enable subprocess role management. When True, child processes can declare different roles and get distinct SPIFFE identities within the same pod.

dict

default:"None"

Multi-region credential configuration.Example: {"aws": "us-west-2", "gcp": "us-central1"}

bool

default:"False"

Enable Agent-to-Agent communication. Starts the A2A bridge (HTTP server on :8080) that receives JSON-RPC messages from the A2A sidecar. Serves an Agent Card at /.well-known/agent.json.

list[dict]

default:"None"

A2A skill declarations for the Agent Card. Each skill has id, name, and description.

skills=[
    {"id": "research", "name": "Research", "description": "Deep web research on any topic"},
    {"id": "summarize", "name": "Summarize", "description": "Summarize long documents"}
]

string

default:"None"

Human-readable description for the Agent Card. Visible to other agents during A2A discovery.

string

default:"None"

Agent version string. Included in Agent Card and OTel spans.

Basic Usage

Function Decorator

from hexr import hexr_agent, hexr_tool

@hexr_agent(name="research-analyst", tenant="acme-corp")
def analyze(topic: str) -> str:
    s3 = hexr_tool("aws_s3")
    # ... your agent logic
    return result

Class Decorator

from hexr import hexr_agent

@hexr_agent(name="content-crew", tenant="acme-corp")
class ContentCrewAgent:
    def run(self, brief: str) -> str:
        # ... multi-step content creation
        return article

What @hexr_agent Does

When you decorate a function or class with @hexr_agent:

Sets Agent Context

Calls HexrContext.set_agent_context() which:

Sets ContextVars (tenant, agent_name, framework, resources)
Writes a process context marker file to /tmp/hexr-context/
Registers the process with the Auto-Registrar

Initializes OpenTelemetry

Creates a TracerProvider and MeterProvider pointing at the OTel Collector. All subsequent SDK calls emit spans and metrics automatically.

Starts A2A Bridge (if a2a=True)

Starts an HTTP server on :8080 that:

Receives /execute calls from the A2A sidecar
Calls your function with the message content
Returns the result as a Task artifact

Wraps Execution

Every invocation of your function/class is wrapped with:

hexr.agent.invoke OTel span
hexr.agent.invocations metric counter
hexr.agent.duration histogram
Error capture and status propagation

Framework Detection

hexr build uses AST analysis (~2,900 lines) to auto-detect your agent framework:

Framework	Detection Pattern
CrewAI	`from crewai import Agent, Crew`
LangChain	`from langchain import ...`, `from langchain_core import ...`
AutoGen	`from autogen import ...`, `AssistantAgent`, `UserProxyAgent`
Strands Agents	`from strands import Agent`, `@tool` decorator
OpenAI Swarm	`from swarm import Swarm`
Pure Python	No framework detected — uses `@hexr_agent` directly

The detected framework is stored in HEXR_FRAMEWORK env var and included in all OTel spans.

A2A Agent Card

When a2a=True, your agent is discoverable by other agents via the A2A protocol:

// GET /.well-known/agent.json
{
  "name": "research-analyst",
  "description": "Deep research and analysis agent",
  "url": "http://research-analyst-a2a.tenant-acme-corp.svc:8090",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "skills": [
    {
      "id": "research",
      "name": "Research",
      "description": "Deep web research on any topic"
    }
  ],
  "securitySchemes": {
    "spiffe": {
      "type": "mtls",
      "trustDomain": "hexr.cloud"
    }
  }
}

Examples

Multi-Cloud Agent

@hexr_agent(
    name="multi-cloud-pipeline",
    tenant="acme-corp",
    resources=["aws_s3", "gcp_bigquery", "azure_storage"],
    regions={"aws": "us-west-2", "gcp": "us-central1"}
)
def pipeline():
    s3 = hexr_tool("aws_s3")
    bq = hexr_tool("gcp_bigquery")
    blob = hexr_tool("azure_storage")

CrewAI with A2A

from crewai import Agent, Crew, Task
from hexr import hexr_agent

@hexr_agent(
    name="content-crew",
    tenant="acme-corp",
    a2a=True,
    skills=[{"id": "content", "name": "Content Creation", "description": "Blog posts and articles"}],
    description="Multi-agent content creation crew"
)
def create_content(brief: str) -> str:
    researcher = Agent(role="Research Analyst", ...)
    writer = Agent(role="Content Writer", ...)
    
    crew = Crew(agents=[researcher, writer], tasks=[...])
    return crew.kickoff()

Subprocess Support

@hexr_agent(
    name="distributed-processor",
    tenant="acme-corp",
    subprocess_support=True
)
def process(data: list):
    # Child processes get distinct SPIFFE IDs
    # spiffe://hexr.cloud/agent/acme-corp/distributed-processor/worker-1
    # spiffe://hexr.cloud/agent/acme-corp/distributed-processor/worker-2
    with ProcessPoolExecutor() as pool:
        results = pool.map(process_chunk, data)

SDK Overview

Decorators & Functions

Modules

@hexr_agent

Signature

Parameters

Basic Usage

Function Decorator

Class Decorator

What @hexr_agent Does

Framework Detection

A2A Agent Card

Examples

Multi-Cloud Agent

CrewAI with A2A

Subprocess Support

​Signature

​Parameters

​Basic Usage

​Function Decorator

​Class Decorator

​What @hexr_agent Does

​Framework Detection

​A2A Agent Card

​Examples

​Multi-Cloud Agent

​CrewAI with A2A

​Subprocess Support

Signature

Parameters

Basic Usage

Function Decorator

Class Decorator

What @hexr_agent Does

Framework Detection

A2A Agent Card

Examples

Multi-Cloud Agent

CrewAI with A2A

Subprocess Support