🎉 SuperOpt is now publicly released — research paper + open-source library

🚀 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.

📖 Documentation | 🌐 Website | 📄 Paper

Problem Setting

Autonomous agents operate in environments composed of prompts, tools, retrieval systems, and memory. Failures often arise from mismatches or inconsistencies in these components rather than from model parameters themselves.

SuperOpt formalizes this setting and provides a structured way to:

• represent agent environments,
• observe execution traces,
• attribute failures, and
• apply targeted environment-level updates.

---

✨ Key Features

🚀 Environment-Level Optimization	🎯 Automatic Failure Diagnosis	🛡️ Stability Guarantees
Optimize prompts, tools, retrieval, and memory as a unified system	Intelligent routing of failures to appropriate optimizers	Hierarchy of mutability prevents oscillation and ensures convergence

📊 Trace-Based Learning	⚡ No Model Retraining	🔧 Framework Agnostic
Uses execution traces as supervision signals	All improvements happen at the environment level	Works with DSPy, CrewAI, AutoGen, and custom agents

🏗️ 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

🎯 SuperController	📝 SuperPrompt	🔧 SuperReflexion	🔍 SuperRAG	🧠 SuperMem
Diagnostic meta-controller for failure routing	Evolutionary instruction optimization (GEPA-based)	Self-healing tool schema repair	Adaptive retrieval optimization	Typed memory with decay and conflict resolution

Citation

If you use this work, please cite:

@misc{superopt2025,
title={SuperOpt: Agentic Environment Optimization for Autonomous AI Agents},
author={Jagtap, Shashi},
year={2025},
note={Under review},
url={https://super-agentic.ai/research/superopt}
}

Status

📌 Under review on public research platforms — early access available via this repository and the project website. Paper is available to read https://super-agentic.ai/papers/SuperOpt.pdf also link to the webpage https://super-agentic.ai/research/superopt

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

Feature	Install Command	Description
🧪 Development	pip install -e ".[dev]"	Testing, linting, formatting tools
🤖 Aider Integration	pip install -e ".[aider]"	Coding agent optimization
🔍 LanceDB RAG	pip install -e ".[lancedb]"	Vector database for retrieval
📦 Everything	pip install -e ".[all]"	All optional dependencies

⚡ Quick Start

🚀 Try It Now

Copy and run this complete example:

# Complete SuperOpt Example - Copy this entire file to test SuperOptfromsuperoptimportSuperOpt, AgenticEnvironmentfromsuperopt.core.environmentimportPromptConfig, ToolSchemafromsuperopt.core.traceimportExecutionTrace, ToolCall# 1. Define your agent's environmentenvironment=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 optimizeroptimizer=SuperOpt(environment=environment)
# 3. Simulate agent execution with a failuretrace=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 optimizeprint("Before optimization:")
print(optimizer.environment.tools['edit_file'].description)
print()
optimizer.step(trace)
# 5. Check the improved environmentprint("After optimization:")
print(optimizer.environment.tools['edit_file'].description)

To test this example:

1. Save the code above as test_superopt.py
2. Run python test_superopt.py
3. You should see the tool description get updated with the 1-indexing constraint

🏃‍♂️ 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

Step	Action	Description
1️⃣	Execute	Run agent task under current environment
2️⃣	Capture	Record structured execution trace
3️⃣	Diagnose	SuperController classifies the failure mode
4️⃣	Route	Send trace to the appropriate optimizer
5️⃣	Generate	Create Natural Language Gradient update
6️⃣	Validate	Check update against stability constraints
7️⃣	Apply	Update environment and persist
8️⃣	Repeat	Continue until convergence

🧩 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

fromsuperopt.adaptersimportAiderAdapterfromsuperoptimportSuperOpt# Create adapter for your Aider instanceadapter=AiderAdapter(
model="gpt-4",
coder_class="EditBlockCoder",
)
# Extract the current environmentenvironment=adapter.extract_environment()
# Initialize optimizeroptimizer=SuperOpt(environment=environment)
# Run optimization episoderesults=optimizer.optimize_episode(
task_description="Fix the failing tests in auth.py",
agent_executor=adapter.execute,
max_iterations=10,
)
# Apply optimized environment back to agentadapter.apply_environment(optimizer.environment)

Custom Agent Integration

fromsuperopt.adapters.baseimportAgentAdapterfromsuperoptimportAgenticEnvironment, ExecutionTraceclassMyAgentAdapter(AgentAdapter):
defextract_environment(self) ->AgenticEnvironment:
"""Extract current environment from your agent."""returnAgenticEnvironment(
prompts=self.agent.get_prompts(),
tools=self.agent.get_tools(),
)
defapply_environment(self, env: AgenticEnvironment) ->None:
"""Apply optimized environment back to agent."""self.agent.set_prompts(env.prompts)
self.agent.set_tools(env.tools)
defexecute(self, task: str) ->ExecutionTrace:
"""Execute task and return trace."""result=self.agent.run(task)
returnself._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:

🔒 Reliability	🛡️ Stability	⚡ Efficiency	🌍 Generalization	👁️ Interpretability
Reduction in repeated failures	Persistence of improvements over time	Token usage, retry counts	Transfer across tasks	Human-readable updates

🔬 Related Research

SuperOpt builds upon groundbreaking work in agent optimization:

🎯 GEPA	🧠 ACE	🎓 Meta-ACE	🔧 DSPy	📝 TextGrad
Evolutionary prompt optimization	Agentic context engineering	Meta-reasoning extensions	Prompt programming framework	Textual differentiation

Agrawal et al. (2025) • Zhang et al. (2025) • Romero (2025) • Khattab et al. (2023) • Yuksekgonul et al. (2024)

🤝 Contributing

We welcome contributions! Here's how to get started:

🚀 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 .

---

📄 License

Apache License 2.0 - see LICENSE file for details.

🤝 Support & Community

📧 Email	🐛 Issues	🌟 Contribute
research@super-agentic.ai	GitHub Issues	Contributing Guide

---

Brought to you 🔥 by Superagentic AI