Architecture

One Rust engine. Five language bindings.

Agentmatic is a Pregel-style graph runtime written in Rust, with thin native bindings for every supported SDK. Same engine, same correctness guarantees, same performance.

Layers

1. SDK layer. Per-language wrappers: agentmatic (PyO3 wheel), @agentmatic/core (napi-rs), agentmatic Rust crate, github.com/neul-labs/agentmatic/sdks/go (CGO), com.agentmatic:agentmatic-core (JNI).
2. Core (Rust). agentmatic-core ships the Pregel runtime + StateGraph + state machine. Lock-free scheduler, SPSC channels, zero-copy Arc<Frame> state diffs.
3. Sub-engines. Checkpointing (Memory / SQLite / Postgres / Redis / S3), Resilience (CB / Retry / DLQ), Distributed runtime (Coordinator/Worker over gRPC).
4. Integrations. LLM providers, MCP client, LangChain bridge, vector stores, OpenTelemetry tracing.

Why Pregel

Pregel is the bulk-synchronous parallel model behind Google's graph systems. It maps cleanly to LangGraph semantics: each step is a superstep, channels are typed reducers, and the scheduler decides what runs in parallel within a step. Crucially, every superstep is a checkpoint boundary — which is what makes time-travel and HITL cheap.

Crates

crates/
├── agentmatic-core/        # Pregel runtime engine
├── agentmatic-agent/       # Agent builder + prebuilt patterns
├── agentmatic-llm/         # LLM provider abstraction
├── agentmatic-tools/       # Tool framework + MCP client
├── agentmatic-memory/      # Conversation memory
├── agentmatic-vectorstore/ # Vector store abstraction
├── agentmatic-types/       # Shared types
├── agentmatic-ffi/         # C ABI for Go/Java bindings
└── agentmatic/             # Umbrella crate

FFI strategy

• Python — PyO3 native extension. Async runs on a dedicated Tokio runtime; Python coroutines bridge via pyo3-asyncio.
• TypeScript — napi-rs prebuilt N-API addons for darwin/linux/windows × x64/arm64.
• Go — CGO over a small C ABI in agentmatic-ffi. Static link by default, no .so on the host.
• Java — JNI over the same C ABI. Prebuilt native libs in the JAR.
• Rust — direct, no FFI.

Observability

OpenTelemetry traces wired into the runtime: every node execution emits a span with tool calls, token counts, and state diffs. RUST_LOG=agentmatic=info dumps structured JSON logs. as_langchain_runnable() wraps the agent so LangSmith traces work unchanged.