Skip to main content

Welcome to FluxLoop

FluxLoop is an open-source toolkit for running reproducible, offline-first simulations of AI agents against dynamic scenarios. It empowers developers to rigorously test agent behavior, evaluate performance against custom criteria, and build confidence before shipping to production.

Why FluxLoop?​

Building trustworthy AI agents requires systematic testing and evaluation. FluxLoop provides:

  • Local-first simulation: Run experiments on your machine with full control
  • Framework-agnostic: Works with any agent framework (LangGraph, LangChain, custom)
  • Argument replay: Record complex function calls once, replay them hundreds of times
  • Structured artifacts: Auditable JSON/JSONL outputs following a documented contract

Quick Start​

Get started in minutes:

# Install packages
pip install fluxloop-cli fluxloop

# Initialize project
fluxloop init project --name my-agent
cd fluxloop/my-agent

# Generate inputs
fluxloop generate inputs --limit 50

# Run experiment
fluxloop run experiment

Documentation Structure​

Core Concepts​

🎯 Decorator-Based Instrumentation​

Add @fluxloop.agent() to your agent function:

import fluxloop

@fluxloop.agent()
def run(input_text: str) -> str:
    return f"Response to: {input_text}"

🔄 Input Generation​

Generate variations using LLM or deterministic strategies:

fluxloop generate inputs --limit 100

🧪 Offline Simulation​

Run experiments locally without cloud dependencies:

fluxloop run experiment

📊 Structured Output​

Every simulation produces auditable artifacts:

  • summary.json - Aggregate statistics
  • trace_summary.jsonl - Per-trace summary records
  • observations.jsonl - Observation stream
  • traces.jsonl - Detailed execution traces

What's Next?​

Choose your path:

Ready to build trustworthy AI agents? Let's get started! 🚀