🎉 SuperOpt is now publicly released — research paper + open-source library
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
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.
| 🚀 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 |
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.
| 🎯 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 |
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}
}📌 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
- 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
pip install superoptgit clone https://github.com/SuperagenticAI/superopt.git
cd superopt
pip install -e .| 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 |
Copy and run this complete example:
# 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)To test this example:
- Save the code above as
test_superopt.py - Run
python test_superopt.py - You should see the tool description get updated with the 1-indexing constraint
python examples/basic_example.pyExpected 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
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 Φ │
└─────────────────────────────────────────────────────────────┘
| 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 |
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
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
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
Adaptive Retrieval Optimization
Dynamically optimizes retrieval-augmented generation systems:
- Optimizes
top_kretrieval 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
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
SuperOpt provides adapters for popular agent frameworks:
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)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)# 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/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 |
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)
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
git clone https://github.com/SuperagenticAI/superopt.git
cd superopt
pip install -e ".[dev]"
# Run tests and quality checks
pytest
black .
ruff check .Apache License 2.0 - see LICENSE file for details.
| 🐛 Issues | 🌟 Contribute | |
|---|---|---|
| research@super-agentic.ai | GitHub Issues | Contributing Guide |
Brought to you 🔥 by Superagentic AI