superagent

README

SuperAgent

SuperAgent is a production-grade AI agent built on Dex durable execution and the released Dex Go SDK. It combines a Go API and Worker with an independently deployable React application. OpenAPI generates both transport boundaries from one contract.

Capabilities

• Durable conversations with typed application history
• Streaming assistant text and provider-authored reasoning summaries
• Plans, tool approvals, user input, steering, and durable timers
• OpenAI, Anthropic, Gemini, Groq, and deterministic mock providers
• MCP over stdio and Streamable HTTP
• Context compaction and Worker replacement recovery
• Atomic Snapshot restoration with best-effort live event reconciliation
• Separately deployable backend and frontend artifacts

The browser restores durable state through one GET /products/ai-agent/snapshot request. It applies Stream updates for low latency and reconciles after durable waits, server errors, explicit requests, and a configurable visible-page Snapshot fallback that defaults to 60 seconds. Refresh recovers only the configured recent Stream tail before resuming live polls.

Architecture

React application ── generated Fetch client ──> Go OpenAPI API
                                                     │
                                                     ├── Dex Client
                                                     └── Dex Worker
                                                              │
                                                              ├── model providers
                                                              └── MCP servers

The Go process never embeds or serves frontend assets. web/dist reads its API origin from config.json, so frontend deployments can change independently of the backend.

The reusable Go package is available at github.com/superdurable/superagent/agent. An embedding application supplies the provider-neutral model and tool boundaries, registers agent.NewFlow(...) with its Dex Worker, and uses agent.NewClient(...) for typed commands, Snapshots, history, and live events. The reference API process uses this same public package; it does not copy or wrap the Agent loop.

The optional github.com/superdurable/superagent/model package exposes the built-in provider router, provider adapters, and process-memory credential store. Embedders can use it without importing SuperAgent internals.

Embedding applications start a non-reusable FlowID with Client.Start and a typed StartRequest. RuntimeMetadata is an optional JSON object of at most 16 KiB for trusted routing data. It is persisted across Worker replacement and passed only to tool implementations, never to models, browser Snapshots, or Streams. Do not put secrets in it.

External tool retries belong to Dex. ToolDefinition controls attempt timeout, maximum attempts, and total duration. A registry performs exactly one call for each Dex attempt.

Commands use Dex transactional RPC semantics. The Agent Client creates one stable application message ID before each Send RPC and preserves it across transport retries and steering. Snapshot exposes those IDs for exact queued-message edit, delete, and steering. After an ambiguous network result, clients read Snapshot to reconcile current durable state instead of consulting stored command receipts. Client.GetArchivedMessages reads one immutable history page without loading the current Agent interaction state.

See ARCHITECTURE.md for package boundaries and durable/live reconciliation. See docs/flow-model.md for the Flow graph and resource model.

Prerequisites

• Go matching go.mod
• Node.js and npm compatible with web/package-lock.json
• A Dex v0.7.0 server
• A writable directory for disposable Dex BlobCache data

Quick start

Install frontend dependencies and build both deployable artifacts:

npm --prefix web ci
make build-api
make build-web

Start a compatible Dex server. Then run the API and Worker:

SUPERAGENT_HTTP_ALLOWED_ORIGINS=http://127.0.0.1:3000 ./bin/superagent

Serve the frontend from a separate terminal:

node script/serve-web.mjs --directory web/dist --port 3000

Open http://127.0.0.1:3000/. The local defaults are:

Component	Address
Frontend	http://127.0.0.1:3000/
API	http://127.0.0.1:8080/
Dex FlowService	127.0.0.1:8801
Dex Worker	127.0.0.1:8803

Use HTTPS for production deployments so browser secure-context APIs remain available.

Configuration

Variable	Purpose	Default
SUPERAGENT_HTTP_ADDRESS	OpenAPI bind address	127.0.0.1:8080
SUPERAGENT_HTTP_ALLOWED_ORIGINS	Exact comma-separated CORS origins	none
SUPERAGENT_STREAM_RECOVERY_LIMIT	Recent events read per Stream on refresh, from 1 through 1000	1000
DEX_FLOW_SERVICE_ADDRESS	Dex FlowService address	127.0.0.1:8801
DEX_WORKER_BIND_ADDRESS	Local Worker bind address	127.0.0.1:8803
DEX_WORKER_TARGET	Worker address advertised to Dex	Worker bind address
DEX_BLOB_CACHE_DIR	Disposable BlobCache directory	/tmp/superagent-blob-cache
DEX_BLOB_CACHE_MAX_BYTES	BlobCache size limit in bytes	536870912
DEX_AGENT_MCP_CONFIG	Trusted MCP YAML path	disabled
OPENAI_API_KEY	OpenAI credential	unset
ANTHROPIC_API_KEY	Anthropic credential	unset
GEMINI_API_KEY	Gemini credential	unset
GROQ_API_KEY	Groq credential	unset

Each provider accepts a trusted HTTPS origin override named <PROVIDER>_BASE_URL. Provider credentials stay in Worker memory and are never persisted in Dex state or logged. Copy web/mcp-servers.example.yaml to configure trusted MCP servers.

For a cross-origin frontend deployment, add its exact origin to SUPERAGENT_HTTP_ALLOWED_ORIGINS. Wildcards and credentialed cross-origin requests are intentionally unsupported. Serve config.json with Cache-Control: no-store and cache fingerprinted frontend releases instead. Its optional positive snapshotRefreshIntervalMilliseconds value configures the visible-page Snapshot fallback. Omission selects 60000.

Development

OpenAPI is the only HTTP contract source. Regenerate and verify both clients:

make generate
make check-generated

Run the complete credential-free quality gate:

make check

make test-public-api also compiles a fixture as a separate Go module. This guards the public import boundary independently of access to internal code.

Run real-server and provider verification explicitly:

DEX_FLOW_SERVICE_ADDRESS=127.0.0.1:8801 make test-dex-integration
make test-openai-live

Only make test-openai-live reads OPENAI_API_KEY from the ignored root .env. Default tests use deterministic fakes or local protocol fixtures.

Flow visualization

Verify that the Go Flow Definition Graph is valid with zero diagnostics:

make check-flow-definition

Render the Go source directly:

make flow-visualize

The command analyzes internal/agent/flow.go, opens Flow Rendering, and serves the graph until stopped. The CI check generates JSON in a temporary directory and rejects every visualizer diagnostic.

Project documentation

• CONTRIBUTING.md: setup, generation, and verification rules
• ARCHITECTURE.md: package and deployment boundaries
• docs/flow-model.md: Flow resources and transitions

Read AGENTS.md before making changes. Work involving Dex Flows, Steps, RPCs, Channels, Streams, Timers, retries, or recovery must also follow the installed Dex Developer skill.