loopengt 0.1.0

Loop Engineering Agent — design, orchestrate, and evaluate agent loops

LOOPENGT — Loop Engineering Agent

Design, orchestrate, and evaluate agent loops — a framework for building production-grade multi-agent workflows with MCP integration and IDE-agnostic plugin architecture.

Features

• 🔄 5 orchestration patterns — sequential, supervisor-worker, parallel fan-out, handoff, evaluator-optimizer
• 🧩 Plugin architecture — extend with custom adapters, tools, templates. Includes built-in plugins for Cursor, Claude Code, Antigravity, and Codex.
• 🧠 Native LLM Integration — Built-in support for OpenAI and Hugging Face Inference Endpoints for autonomous loop orchestration.
• 🔌 MCP server — expose loop tools to Cursor, Claude Code, Antigravity
• 📊 Built-in tracing — SQLite + JSONL traces with OpenTelemetry export
• 🧪 Evaluation framework — built-in metrics + LLM-as-judge
• 📝 5 built-in templates — planner-executor, reviewer-retry, supervisor-workers, research-architect, handoff loop
• ⚡ Async-first — built on anyio for concurrent execution

Quick Start

# Create and activate a virtual environment
uv venv
.venv\Scripts\activate  # On Windows
# source .venv/bin/activate  # On macOS/Linux

# Install the base package
uv pip install loopengt

# With MCP support
uv pip install "loopengt[mcp]"

# With everything
uv pip install "loopengt[all]"

Initialize

loopengt init

Creates a .loopengt/ directory with configuration, templates, and prompts.

Design a Loop

loopengt design "code review loop with automated testing"

Generates loop.yaml and LOOP_DESIGN.md.

Execute

loopengt run loop.yaml

Inspect Traces

loopengt trace <run_id>

Evaluate

loopengt eval <run_id>

How to Engineer a Loop (Step-by-Step Guide)

Building an autonomous agent loop with LOOPENGT involves designing the architecture, defining the agents, and orchestrating their workflow. Here is the recommended workflow for engineering a new loop from scratch:

Step 1: Initialize Your Workspace

First, set up the necessary project configurations by running:

loopengt init

This scaffolds a .loopengt/ directory in your project containing configuration files, built-in templates, and prompts.

Step 2: Set Your LLM Provider

Ensure your environment is configured for the LLM that will both design and run your agents. For example, to use OpenAI:

export OPENAI_API_KEY="your-api-key"
export LOOPENGT_LLM_PROVIDER="openai"

Step 3: Design the Loop

Instead of writing the YAML specification manually, use the built-in AI Architect to design the loop for you. Provide a clear goal:

loopengt design "create a content generation loop where a Researcher finds facts, a Writer drafts an article, and an Editor reviews it for quality."

The architect will generate two files:

• LOOP_DESIGN.md: A human-readable breakdown of the agents, their roles, and the orchestration strategy.
• loop.yaml: The executable Pydantic-serializable configuration file.

Step 4: Refine the Configuration (Optional)

Open loop.yaml in your editor. You can manually tweak:

• Agents: Adjust system prompts, input/output schemas, or LLM settings.
• Tools: Add native functions or MCP integrations.
• Policies: Set retry limits, turn budgets, or verification gates.

Step 5: Execute the Loop

Run the orchestrator using your generated specification:

loopengt run loop.yaml

Watch the terminal as the Executor coordinates the agents (Researcher -> Writer -> Editor) based on the chosen pattern (e.g., sequential or supervisor-worker).

Step 6: Trace and Evaluate

Once the run completes, inspect the detailed execution trace to debug or review agent interactions:

# List recent runs to find the ID
ls .loopengt/runs/

# Inspect the trace
loopengt trace <run_id>

If you want to score the quality of the final output, run the evaluator:

loopengt eval <run_id>

Architecture

CLI / IDE Adapters → MCP Server → Plugin System → Core Runtime → Models
                                                        ↓
                                              Tracing & Memory → Storage

See ARCHITECTURE.md for details.

Orchestration Patterns

Pattern	Description	Use Case
sequential	Steps execute in order	Simple workflows
supervisor_worker	Supervisor delegates to workers	Complex tasks
parallel_fan_out	Independent steps run concurrently	Batch processing
handoff	Agents pass enriched context along	Pipelines
evaluator_optimizer	Iterative quality improvement	Code review

MCP Integration

Start the MCP server:

loopengt mcp --transport stdio

Add to Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "loopengt": {
      "command": "loopengt",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}

CLI Commands

Command	Description
loopengt init	Scaffold .loopengt/ project directory
loopengt design "goal"	Design a loop from a goal
loopengt run <spec>	Execute a loop spec
loopengt trace <id>	Inspect execution trace
loopengt eval <id>	Run evaluations
loopengt template list	List available templates
loopengt doctor	Diagnose configuration
loopengt mcp	Start MCP server

Development

git clone https://github.com/Sriramdayal/LOOPENGT.git
cd LOOPENGT
uv pip install -e ".[dev]"


# Lint
ruff check src/ tests/

# Type check
mypy src/loopengt/

# Test
pytest tests/ -v

Plugin Development

See docs/plugin_dev.md for the plugin development guide.

Examples

Check out the examples/ directory for programmatic usage:

• examples/basic_loop.py — A simple sequential loop setup.
• examples/multi_agent_loop.py — A complex Supervisor-Worker multi-agent orchestration.

License

GPL-3.0