Aetheris — Durable Execution Runtime for AI Agents

Why Aetheris

Production agents fail in ways
your code doesn't handle.

Happy-path code runs fine in demos. In production, workers crash mid-run, retries duplicate payments, and nobody can prove what the agent actually did.

Without Aetheris

✗ Worker crash → entire task restarts from zero
✗ Retry logic re-sends emails, re-charges cards
✗ No audit trail → impossible post-incident analysis
✗ Human-in-the-loop requires custom state machines
✗ Long-running jobs silently timeout with no recovery

With Aetheris

✓ Resume from last durable checkpoint automatically
✓ Invocation ledger guarantees at-most-once execution
✓ Every transition traced, replayable, and auditable
✓ StatusParked for wait states — no custom state machine
✓ Lease fencing keeps jobs alive across worker restarts

Architecture

Drop in the runtime.
Keep your agent logic.

Aetheris sits between your agent and the outside world. You submit work via HTTP or Go SDK; the runtime handles durability, scheduling, and side-effect safety.

Your Agent

Python · Go · HTTP

→

Aetheris API

POST /agents/:id/message

→

Aetheris Runtime

Planner → RoutingAdvisor → TaskGraph → Executor

→

Tool Ledger

At-most-once guarantees

→

External Tools

APIs · DBs · Services

PostgreSQL job store Checkpoint runner Lease fencing DAG compiler OpenTelemetry traces Replay engine Routing advisor Embedded bridge

Core Guarantees

Three properties you can
reason about formally.

Aetheris is built around a small set of guarantees that compose correctly. Each one has a formal definition in the runtime spec.

⚡

Crash Recovery

When a worker dies, the scheduler's lease fencing detects the timeout and assigns the job to the next available worker, which resumes from the last committed checkpoint. Zero manual intervention required.

// Job resumes from checkpoint on worker restart func Resume(ctx context.Context, jobID string) error { checkpoint, _ := store.LoadCheckpoint(jobID) return runner.ContinueFrom(ctx, checkpoint) }

🔒

At-most-once Execution

Every tool invocation is recorded in an immutable ledger before execution. On retry, the runtime checks the ledger — if the call already happened, the recorded result is returned without re-executing.

// Ledger prevents duplicate side effects if result, ok := ledger.Lookup(invocationID); ok { return result, nil // idempotent reply } return tool.Execute(ctx, params)

🔍

Replayable Audit Trail

Every state transition is appended to a durable event log with full causality. Any job can be replayed step-by-step for debugging, compliance review, or post-incident root cause analysis.

// Full trace for any job curl /api/jobs/{id}/trace/page // Deterministic replay in sandbox aetheris replay --job job_abc123

Advanced Features

Enterprise-grade capabilities
for production workloads.

From intelligent routing to embedded framework bridges — Aetheris provides the building blocks for sophisticated agent orchestration.

🏗️

Embedded Runtime Bridge

Integrate 8+ Go agent frameworks directly as TaskGraph nodes. LangChainGo, LangGraphGo, Google ADK, Firebase Genkit, and more run natively inside the Aetheris runtime with full checkpoint support.

// Register embedded framework agent agents: my_langchain_agent: type: "langchaingo" tools: ["web_search", "calculator"]

🧠

Routing Advisor

Intelligent capability routing based on content analysis. The RoutingAdvisor interface enables WisePick-style dynamic tool selection with durable evidence recording for replay safety.

// Content-hash based routing routing: advisor: type: "content_hash" config: strategy: "consistent"

🔗

LangGraph Integration

Expose Python LangGraph compiled graphs as Aetheris-compatible HTTP agents. Use embedded manifest mode for step-level control or black-box mode for quick migration.

// LangGraph as embedded agent agents: research_agent: type: "langgraph" external: mode: "embedded" manifest: "./manifest.json"

📡

SSE Streaming Protocol

Native support for Server-Sent Events streaming agents. The sse_legacy protocol enables integration with platforms like superagent-base for real-time token streaming.

// SSE-streaming agent config agents: streaming_agent: type: "external_http" external: protocol: "sse_legacy" url: "http://agent:8888/stream"

Quickstart

Running in under 3 minutes.

Clone, start the embedded runtime, and submit your first durable job. No cloud account, no Kubernetes, no configuration files required.

1

Clone and start

git clone https://github.com/Colin4k1024/Aetheris.git
cd Aetheris
make run-embedded

2

Verify the runtime is live

curl http://localhost:8080/api/health

3

Submit your first message

curl -X POST http://localhost:8080/api/agents/default/message \
  -H "Content-Type: application/json" \
  -d '{"content": "Summarize the top 3 HN stories"}'

1

Register an external HTTP agent

# configs/agents.yaml
agents:
  my_agent:
    type: "external_http"
    description: "My agent (JSON mode)"
    external:
      url: "http://localhost:9000/invoke"
      timeout: "30s"
      token_env: "MY_AGENT_API_KEY"

  # SSE-streaming agent (e.g. superagent-base)
  streaming_agent:
    type: "external_http"
    external:
      url: "http://localhost:8888/api/v1/chat/stream"
      timeout: "120s"
      protocol: "sse_legacy"
      agent_id: "research-agent"

2

Start your agent server

# Python example (any HTTP server works)
from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/run', methods=['POST'])
def run():
    goal = request.json['goal']
    return jsonify({'answer': f'Done: {goal}'})

3

Submit work via Aetheris

curl -X POST http://localhost:8080/api/agents/my-agent/message \
  -H "Content-Type: application/json" \
  -d '{"content": "your goal here"}'

1

Install the Python SDK

pip install aetheris-sdk

2

Submit a durable job

from aetheris import Client

client = Client("http://localhost:8080")
job = client.submit(
    agent="default",
    message="Summarize the report",
)
print(job.id, job.status)

3

Inspect the trace

trace = client.trace(job.id)
for step in trace.steps:
    print(step.name, step.status, step.duration_ms)

Key endpoints

GET

/api/health

Runtime liveness check

POST

/api/agents/:id/message

Submit work to an agent

GET

/api/jobs/:id/trace/page

View step-level execution trace

GET

/metrics

Prometheus metrics

Verified Proof

README scenarios, run for real.

These recordings come from the embedded quickstart and the external_http batch demo, with raw job, event, and trace evidence checked into the repository.