🚀 SuperOpt

Agentic Environment Optimization for Autonomous AI Agents

SuperOpt is a unified framework for optimizing agent environments (prompts, tools, retrieval, memory) without modifying model parameters. It treats the entire agent environment as a structured optimization target, enabling autonomous agents to self-correct and stabilize over time.

✨ Key Features

🏗️ Architecture Overview

SuperOpt formalizes optimization as iterative descent over Natural Language Gradients derived from execution traces. A meta-diagnostic controller attributes failures to specific environment layers and routes corrective updates to specialized optimization engines.

Core Components

Research Paper

The research paper describing SuperOpt has been uploaded and will be available soon after launch.

Key Features

• Environment-Level Optimization: Optimize prompts, tools, retrieval, and memory as a unified system
• Failure Attribution: Automatic diagnosis and routing of failures to appropriate optimizers
• Stability Guarantees: Hierarchy of mutability prevents oscillation and ensures convergence
• Trace-Based Learning: Uses execution traces as supervision signals
• No Model Retraining: All improvements happen at the environment level

📦 Installation

Quick Install

pip install superopt

From Source

git clone https://github.com/SuperagenticAI/superopt.git
cd superopt
pip install -e .

Optional Dependencies

⚡ Quick Start

🚀 Try It Now

# Complete SuperOpt Example - Copy this entire file to test SuperOpt
from superopt import SuperOpt, AgenticEnvironment
from superopt.core.environment import PromptConfig, ToolSchema
from superopt.core.trace import ExecutionTrace, ToolCall

# 1. Define your agent's environment
environment = AgenticEnvironment(
    prompts=PromptConfig(
        system_prompt="You are a helpful coding assistant."
    ),
    tools={
        "edit_file": ToolSchema(
            name="edit_file",
            description="Edit a file at a specific line",
            arguments={"file": "str", "line": "int"},
        ),
    },
)

# 2. Initialize the optimizer
optimizer = SuperOpt(environment=environment)

# 3. Simulate agent execution with a failure
trace = ExecutionTrace(
    task_description="Edit line 0 in test.py",
    success=False,
)
trace.tool_errors.append(ToolCall(
    tool_name="edit_file",
    arguments={"file": "test.py", "line": 0},
    error_message="Line numbers must be 1-indexed",
))

# 4. Let SuperOpt learn and optimize
print("Before optimization:")
print(optimizer.environment.tools['edit_file'].description)
print()

optimizer.step(trace)

# 5. Check the improved environment
print("After optimization:")
print(optimizer.environment.tools['edit_file'].description)

🏃‍♂️ Run the Official Example

python examples/basic_example.py

Expected Output:

SuperOpt Basic Example
==================================================

1. Initial Environment:
   Tool schema description: Edit a file by applying changes...

2. Executing task with tool error...
   Error: Line numbers must be 1-indexed, not 0-indexed

3. Optimizing environment...

4. Updated Environment:
   Tool schema description length: 126 chars
   ✓ Schema was updated with clarifications

5. Statistics:
   Controller diagnoses: {'PROMPT': 0, 'TOOL': 1, 'RETRIEVAL': 0, 'MEMORY': 0, 'NONE': 0}
   Optimization steps: 1

🔄 How SuperOpt Works

SuperOpt operates in an outer optimization loop surrounding the agent execution loop:

┌─────────────────────────────────────────────────────────────┐
│                    🚀 SuperOpt Optimization Loop             │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                  🤖 Agent Execution Loop                 ││
│  │   Task → Agent → Tool Calls → Results → Output          ││
│  └─────────────────────────────────────────────────────────┘│
│                           │                                  │
│                    📊 Execution Trace                        │
│                           ↓                                  │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              🎯 SuperController (Diagnosis)              ││
│  │   Classify failure: PROMPT | TOOL | RETRIEVAL | MEMORY  ││
│  └─────────────────────────────────────────────────────────┘│
│                           │                                  │
│         ┌─────────────────┼─────────────────┐               │
│         ↓                 ↓                 ↓               │
│   ┌──────────┐     ┌──────────┐     ┌──────────┐           │
│   │📝 Super- │     │🔧 Super-   │     │🔍 Super- │           │
│   │   Prompt │     │ Reflexion │     │   RAG   │           │
│   │(Prompts) │     │  (Tools)  │     │(Retrieval)│          │
│   └──────────┘     └──────────┘     └──────────┘           │
│         │                 │                 │               │
│         └─────────────────┼─────────────────┘               │
│                           ↓                                  │
│              🌟 Natural Language Gradient (∇_NL)            │
│                           ↓                                  │
│                  ✨ Updated Environment Φ                   │
└─────────────────────────────────────────────────────────────┘

📋 Optimization Workflow

🧩 Core Components

🎯 SuperController

Diagnostic Meta-Controller

The intelligent orchestrator that analyzes execution traces and routes optimization tasks to the appropriate component:

• PROMPT: Handles instruction violations, format errors, and unclear prompts
• TOOL: Detects schema violations, invalid arguments, and tool misuse
• RETRIEVAL: Identifies missing symbols, empty results, and retrieval failures
• MEMORY: Catches repeated mistakes, contradictions, and memory issues

📝 SuperPrompt

Evolutionary Prompt Optimizer

Advances prompt engineering through systematic optimization:

• Reflective mutation guided by execution traces and failure patterns
• Pareto-based selection across multiple objectives (accuracy, efficiency, clarity)
• Population-based search using GEPA methodology for prompt evolution
• Automatic prompt refinement based on real-world performance data

🔧 SuperReflexion

Self-Healing Tool Schemas

Automatically repairs and enhances tool definitions when agents encounter issues:

• Analyzes tool failures and error patterns in real-time
• Generates schema clarifications and constraint additions automatically
• Appends important constraints to tool descriptions to prevent future errors
• Learns from agent mistakes to improve tool reliability

🔍 SuperRAG

Adaptive Retrieval Optimization

Dynamically optimizes retrieval-augmented generation systems:

• Optimizes top_k retrieval count based on query complexity and context
• Adapts chunk size and overlap for better semantic understanding
• Tunes reranking thresholds to improve result relevance
• Automatically switches between semantic vs structural retrieval modes

🧠 SuperMem

Intelligent Memory System

Advanced memory management with hierarchical organization:

• Type hierarchy: TOOL_RULE > RAG_HEURISTIC > STRATEGY for organized knowledge
• Exponential decay: Relevance-based forgetting to maintain current knowledge
• Conflict resolution: Automatic detection and resolution of contradictory information
• Confidence tracking: Validation and uncertainty quantification for memory entries

Integration with Agents

SuperOpt provides adapters for popular agent frameworks:

Using with Aider

from superopt.adapters import AiderAdapter
from superopt import SuperOpt

# Create adapter for your Aider instance
adapter = AiderAdapter(
    model="gpt-4",
    coder_class="EditBlockCoder",
)

# Extract the current environment
environment = adapter.extract_environment()

# Initialize optimizer
optimizer = SuperOpt(environment=environment)

# Run optimization episode
results = optimizer.optimize_episode(
    task_description="Fix the failing tests in auth.py",
    agent_executor=adapter.execute,
    max_iterations=10,
)

# Apply optimized environment back to agent
adapter.apply_environment(optimizer.environment)

Custom Agent Integration

from superopt.adapters.base import AgentAdapter
from superopt import AgenticEnvironment, ExecutionTrace

class MyAgentAdapter(AgentAdapter):
    def extract_environment(self) -> AgenticEnvironment:
        """Extract current environment from your agent."""
        return AgenticEnvironment(
            prompts=self.agent.get_prompts(),
            tools=self.agent.get_tools(),
        )

    def apply_environment(self, env: AgenticEnvironment) -> None:
        """Apply optimized environment back to agent."""
        self.agent.set_prompts(env.prompts)
        self.agent.set_tools(env.tools)

    def execute(self, task: str) -> ExecutionTrace:
        """Execute task and return trace."""
        result = self.agent.run(task)
        return self._create_trace(result)

📊 Evaluation & Benchmarks

🏃‍♂️ Run Evaluations

# Quick evaluation on sample tasks
python scripts/evaluate_baseline.py --tasks data/tasks/sample_tasks.json
python scripts/evaluate_superopt.py --tasks data/tasks/sample_tasks.json
python scripts/compare_all.py --tasks data/tasks/sample_tasks.json

# Analyze results
python scripts/analyze_results.py --results-dir results/

📈 Evaluation Metrics

SuperOpt evaluates improvements across multiple dimensions:

🔬 Related Research

SuperOpt builds upon groundbreaking work in agent optimization:

🤝 Contributing

🚀 Quick Start

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

🛠️ Development Setup

git clone https://github.com/SuperagenticAI/superopt.git
cd superopt
pip install -e ".[dev]"

# Run tests and quality checks
pytest
black .
ruff check .