AgentFabric

AgentFabric is a multi-agent collaboration runtime for openEuler/Linux. The project focuses on structured communication, typed non-text state exchange, and reusable cross-task memory.

The original competition statement and scoring requirements are preserved in docs/competition-requirements.md.

Current milestone

The repository has completed the reproducible four-mode experiment milestone. It currently provides:

• A Rust workspace for the runtime, protocol, transport, state bus, and metrics.
• Generated Rust and Python bindings from one versioned AFP/1 Protocol Buffers schema.
• A Python SDK with framed transport and five deterministic reference capabilities.
• A fail-closed capability registry with duplicate-agent and ambiguous-action rejection.
• Runtime routing across independently connected Planner, Retriever, and Summarizer Agents.
• A three-step structured workflow with message and wire-byte accounting.
• A mmap-backed binary state plane using /dev/shm on Linux and a temporary-file fallback on Windows development hosts.
• Typed Embedding references with shape, dtype, producer, model, expiry, purpose, and CRC32 integrity metadata.
• State publish, consumer lease, release, producer retirement, and TTL reap lifecycle controls.
• SQLite-authoritative shared memory with complete source, topic, summary, tag, evidence, content, confidence, status, and reuse metadata.
• Explainable hybrid retrieval combining deterministic semantic similarity, keyword overlap, and tag overlap without requiring an external vector service.
• Ten related tasks per group on persistent Agent sessions where B3 reuses memory for nine tasks and skips nine Retriever executions.
• Comparable B0 text, B1 structured, B2 state-enhanced, and B3 memory-enhanced collaboration modes on one runtime event model and one quality contract.
• Two versioned continuous task groups, randomized mode ordering, ten repetitions per cell, task hashes, environment and Git-state capture, failure preservation, raw JSONL samples, and generated Markdown reports.
• Information-equivalent 256-dimensional B1/B2 state ablation with a session-scoped mmap slot.
• Labeled memory interference evaluation, cross-process persistence, and 100-task state endurance.
• Enforced communication, state, memory, and latency thresholds for formal release-mode runs.
• Unit and end-to-end tests behind a single build/test entry point.

The next milestone hardens long-session stability and introduces optional CodeAct execution with a fail-closed isolation policy. Final openEuler acceptance and release documentation follow it.

Milestone 5 is accepted as an engineering foundation, not as final competition evidence. Its measured limitations, optimization strategy, and claim boundaries are documented in docs/milestones/0005-four-mode-experiment-review.md. Quantified follow-up acceptance targets are tracked in docs/project-goals.md; documenting them does not start the next milestone.

The completed optimization pass and clean 240-sample evidence are recorded in docs/milestones/0005-optimization-results.md.

Repository layout

crates/       Rust runtime and Linux system components
proto/        AFP versioned protocol schemas
python/       Python SDK and reference agents
benchmarks/   Reproducible task sets and evaluators
configs/      Versioned runtime and experiment configuration
deploy/       openEuler deployment assets
docs/         Architecture decisions and engineering documentation
scripts/      Developer and verification commands
tests/        Cross-component and end-to-end tests

Development commands

On openEuler or another Linux development host with Rust 1.75+ and Python 3.11+:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ./python
make build
make test
make check
cargo run -p agentfabric-runtime -- serve
cargo run -p agentfabric-runtime -- serve-workflow --agents 3
cargo run -p agentfabric-runtime -- serve-state-workflow --agents 3
cargo run -p agentfabric-runtime -- serve-memory-workflow --agents 3
cargo build -p agentfabric-runtime --release
PYTHONPATH=python/src python benchmarks/run_experiment.py --repetitions 30 --random-seed 20260724

Rust bindings are generated during Cargo builds with a vendored protoc. The committed Python binding is generated from proto/afp/v1/afp.proto; runtime code must not hand-maintain duplicate message definitions. Dependency and compatibility rationale is recorded in docs/adr/0001-protobuf-code-generation.md.

Capability registration and deterministic routing are described in docs/adr/0002-capability-routing-and-workflow.md.

The non-text state plane and lifecycle contract are described in docs/adr/0003-mmap-state-plane.md.

Shared memory persistence and hybrid retrieval are described in docs/adr/0004-sqlite-shared-memory.md.

Four-mode experiment comparability and evidence rules are described in docs/adr/0005-reproducible-four-mode-experiments.md. Benchmark operation and current development measurements are in benchmarks/README.md.

On Windows, use the Rust x86_64-pc-windows-gnullvm host toolchain together with LLVM-MinGW, or the standard MSVC toolchain with Visual Studio Build Tools. Windows TCP loopback is a development fallback; Unix domain transport remains the Linux target.

Target platform

• Required: openEuler 24.03-LTS-SP3 on x86_64.
• Target compatibility: openEuler 24.03-LTS-SP3 on AArch64.
• Development fallback: Windows can inspect and edit the repository, but Linux-specific transport and shared-memory tests run on Linux.

Project rules

• Keep TEXT, STRUCTURED, STATE, and MEMORY benchmark modes semantically comparable.
• Do not claim performance improvements without versioned raw measurements.
• Keep the control plane independent from large state payloads.
• Treat embeddings as routing and retrieval features, not lossless replacements for evidence.